erk 0.4.5__py3-none-any.whl

erk/artifacts/discovery.py

@@ -0,0 +1,343 @@
+"""Discover artifacts installed in a project's .claude/ and .github/ directories."""
+
+import hashlib
+import json
+from pathlib import Path
+
+from erk.artifacts.models import ArtifactType, InstalledArtifact
+from erk.core.claude_settings import (
+    ERK_EXIT_PLAN_HOOK_COMMAND,
+    ERK_USER_PROMPT_HOOK_COMMAND,
+)
+
+
+def _compute_file_hash(path: Path) -> str:
+    """Compute SHA256 hash of single file content."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+
+
+def _compute_directory_hash(path: Path) -> str:
+    """Compute combined hash of all files in directory.
+
+    Includes relative path in hash to detect structural changes (renames, moves).
+    Files are processed in sorted order for deterministic hashing.
+    """
+    hasher = hashlib.sha256()
+    for file_path in sorted(path.rglob("*")):
+        if file_path.is_file():
+            # Include relative path in hash for structural changes
+            hasher.update(file_path.relative_to(path).as_posix().encode())
+            hasher.update(file_path.read_bytes())
+    return hasher.hexdigest()[:16]
+
+
+def _compute_hook_hash(command: str) -> str:
+    """Compute hash of hook command string."""
+    return hashlib.sha256(command.encode()).hexdigest()[:16]
+
+
+def _compute_content_hash(path: Path) -> str:
+    """Compute SHA256 hash of file or directory content.
+
+    For files: hashes the file content directly.
+    For directories: hashes all files with their relative paths.
+    """
+    if path.is_dir():
+        return _compute_directory_hash(path)
+    return _compute_file_hash(path)
+
+
+def _discover_skills(claude_dir: Path) -> list[InstalledArtifact]:
+    """Discover skills in .claude/skills/ directory.
+
+    Skills are identified by their SKILL.md entry point file.
+    Pattern: skills/<skill-name>/SKILL.md
+
+    Content hash is computed over the entire skill directory (all files),
+    not just the SKILL.md entry point.
+    """
+    skills_dir = claude_dir / "skills"
+    if not skills_dir.exists():
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+    for skill_dir in skills_dir.iterdir():
+        if not skill_dir.is_dir():
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if skill_file.exists():
+            artifacts.append(
+                InstalledArtifact(
+                    name=skill_dir.name,
+                    artifact_type="skill",
+                    path=skill_file,
+                    # Hash the entire skill directory, not just SKILL.md
+                    content_hash=_compute_directory_hash(skill_dir),
+                )
+            )
+    return artifacts
+
+
+def _discover_commands(claude_dir: Path) -> list[InstalledArtifact]:
+    """Discover commands in .claude/commands/ directory.
+
+    Commands can be:
+    - Top-level: commands/<command>.md (no namespace)
+    - Namespaced: commands/<namespace>/<command>.md
+    """
+    commands_dir = claude_dir / "commands"
+    if not commands_dir.exists():
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+
+    # Discover top-level commands (no namespace)
+    for cmd_file in commands_dir.glob("*.md"):
+        artifacts.append(
+            InstalledArtifact(
+                name=cmd_file.stem,
+                artifact_type="command",
+                path=cmd_file,
+                content_hash=_compute_content_hash(cmd_file),
+            )
+        )
+
+    # Discover namespaced commands
+    for namespace_dir in commands_dir.iterdir():
+        if not namespace_dir.is_dir():
+            continue
+        for cmd_file in namespace_dir.glob("*.md"):
+            # Name includes namespace: "local:fast-ci" or "erk:plan-implement"
+            name = f"{namespace_dir.name}:{cmd_file.stem}"
+            artifacts.append(
+                InstalledArtifact(
+                    name=name,
+                    artifact_type="command",
+                    path=cmd_file,
+                    content_hash=_compute_content_hash(cmd_file),
+                )
+            )
+    return artifacts
+
+
+def _discover_agents(claude_dir: Path) -> list[InstalledArtifact]:
+    """Discover agents in .claude/agents/ directory.
+
+    Supports two patterns:
+    1. Directory-based: agents/<name>/<name>.md (hash computed over entire directory)
+    2. Single-file: agents/<name>.md (hash computed over single file)
+
+    Directory-based agents take precedence if both exist.
+    """
+    agents_dir = claude_dir / "agents"
+    if not agents_dir.exists():
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+
+    # First, discover directory-based agents: agents/<name>/<name>.md
+    for item in agents_dir.iterdir():
+        if item.is_dir():
+            agent_file = item / f"{item.name}.md"
+            if agent_file.exists():
+                artifacts.append(
+                    InstalledArtifact(
+                        name=item.name,
+                        artifact_type="agent",
+                        path=agent_file,
+                        content_hash=_compute_directory_hash(item),
+                    )
+                )
+
+    # Track discovered names to avoid duplicates
+    discovered_names = {a.name for a in artifacts}
+
+    # Second, discover single-file agents: agents/<name>.md
+    for item in agents_dir.iterdir():
+        if item.is_file() and item.suffix == ".md":
+            name = item.stem
+            if name not in discovered_names:
+                artifacts.append(
+                    InstalledArtifact(
+                        name=name,
+                        artifact_type="agent",
+                        path=item,
+                        content_hash=_compute_file_hash(item),
+                    )
+                )
+
+    return artifacts
+
+
+def _discover_workflows(workflows_dir: Path) -> list[InstalledArtifact]:
+    """Discover all workflows in .github/workflows/ directory.
+
+    Discovers all .yml and .yaml files in the workflows directory.
+
+    Pattern: .github/workflows/<name>.yml
+    """
+    if not workflows_dir.exists():
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+    for workflow_file in workflows_dir.iterdir():
+        if not workflow_file.is_file():
+            continue
+        if workflow_file.suffix not in (".yml", ".yaml"):
+            continue
+        artifacts.append(
+            InstalledArtifact(
+                name=workflow_file.stem,
+                artifact_type="workflow",
+                path=workflow_file,
+                content_hash=_compute_content_hash(workflow_file),
+            )
+        )
+    return artifacts
+
+
+def _discover_actions(actions_dir: Path) -> list[InstalledArtifact]:
+    """Discover all actions in .github/actions/ directory.
+
+    Actions are directories containing an action.yml or action.yaml file.
+
+    Pattern: .github/actions/<name>/action.yml
+    """
+    if not actions_dir.exists():
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+    for action_path in actions_dir.iterdir():
+        if not action_path.is_dir():
+            continue
+        # Look for action.yml or action.yaml
+        action_file = action_path / "action.yml"
+        if not action_file.exists():
+            action_file = action_path / "action.yaml"
+        if not action_file.exists():
+            continue
+        artifacts.append(
+            InstalledArtifact(
+                name=action_path.name,
+                artifact_type="action",
+                path=action_file,
+                content_hash=_compute_directory_hash(action_path),
+            )
+        )
+    return artifacts
+
+
+def _extract_hook_name(command: str) -> str:
+    """Extract a meaningful name from a hook command.
+
+    For erk hooks, returns the known name.
+    For local hooks, returns the full command text for identification.
+    """
+    # Check for erk-managed hooks first
+    if command == ERK_USER_PROMPT_HOOK_COMMAND:
+        return "user-prompt-hook"
+    if command == ERK_EXIT_PLAN_HOOK_COMMAND:
+        return "exit-plan-mode-hook"
+
+    # For local hooks, use the full command text as the identifier
+    return command
+
+
+def _discover_hooks(claude_dir: Path) -> list[InstalledArtifact]:
+    """Discover all hooks configured in .claude/settings.json.
+
+    Hooks are configuration entries in settings.json, not files.
+    Discovers both erk-managed hooks and local/user-defined hooks.
+
+    Pattern: hooks.<HookType>[].hooks[].command
+    """
+    settings_path = claude_dir / "settings.json"
+    if not settings_path.exists():
+        return []
+
+    content = settings_path.read_text(encoding="utf-8")
+    settings = json.loads(content)
+    hooks_section = settings.get("hooks", {})
+    if not hooks_section:
+        return []
+
+    artifacts: list[InstalledArtifact] = []
+    seen_names: set[str] = set()
+
+    # Iterate through all hook types (UserPromptSubmit, PreToolUse, etc.)
+    for hook_entries in hooks_section.values():
+        if not isinstance(hook_entries, list):
+            continue
+        for entry in hook_entries:
+            if not isinstance(entry, dict):
+                continue
+            for hook in entry.get("hooks", []):
+                if not isinstance(hook, dict):
+                    continue
+                command = hook.get("command")
+                if not command:
+                    continue
+
+                name = _extract_hook_name(command)
+
+                # Avoid duplicates
+                if name in seen_names:
+                    continue
+                seen_names.add(name)
+
+                artifacts.append(
+                    InstalledArtifact(
+                        name=name,
+                        artifact_type="hook",
+                        path=settings_path,
+                        content_hash=_compute_hook_hash(command),
+                    )
+                )
+
+    return artifacts
+
+
+def discover_artifacts(project_dir: Path) -> list[InstalledArtifact]:
+    """Scan project directory and return all installed artifacts.
+
+    Discovers:
+    - skills: .claude/skills/<name>/SKILL.md
+    - commands: .claude/commands/<namespace>/<name>.md
+    - agents: .claude/agents/<name>/<name>.md
+    - workflows: .github/workflows/<name>.yml (all workflows)
+    - actions: .github/actions/<name>/action.yml (all actions)
+    - hooks: configured in .claude/settings.json
+    """
+    claude_dir = project_dir / ".claude"
+    workflows_dir = project_dir / ".github" / "workflows"
+    actions_dir = project_dir / ".github" / "actions"
+
+    artifacts: list[InstalledArtifact] = []
+
+    if claude_dir.exists():
+        artifacts.extend(_discover_skills(claude_dir))
+        artifacts.extend(_discover_commands(claude_dir))
+        artifacts.extend(_discover_agents(claude_dir))
+        artifacts.extend(_discover_hooks(claude_dir))
+
+    artifacts.extend(_discover_workflows(workflows_dir))
+    artifacts.extend(_discover_actions(actions_dir))
+
+    # Sort by type then name for consistent output
+    return sorted(artifacts, key=lambda a: (a.artifact_type, a.name))
+
+
+def get_artifact_by_name(
+    project_dir: Path, name: str, artifact_type: ArtifactType | None
+) -> InstalledArtifact | None:
+    """Find a specific artifact by name.
+
+    If artifact_type is provided, only search that type.
+    Otherwise, search all types and return first match.
+    """
+    artifacts = discover_artifacts(project_dir)
+    for artifact in artifacts:
+        if artifact.name == name:
+            if artifact_type is None or artifact.artifact_type == artifact_type:
+                return artifact
+    return None

erk/artifacts/models.py

@@ -0,0 +1,63 @@
+"""Data models for artifact management."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+# Type of artifact based on directory structure in .claude/ or .github/
+# Note: "hook" is not file-based like others; it's a config entry in settings.json
+ArtifactType = Literal["skill", "command", "agent", "workflow", "action", "hook"]
+
+
+@dataclass(frozen=True)
+class InstalledArtifact:
+    """An artifact installed in a project's .claude/ directory."""
+
+    name: str
+    artifact_type: ArtifactType
+    path: Path
+    # Content hash for staleness detection (optional)
+    content_hash: str | None
+
+
+@dataclass(frozen=True)
+class ArtifactFileState:
+    """Per-artifact state tracking version and hash at sync time."""
+
+    version: str  # erk version when this artifact was synced
+    hash: str  # content hash at sync time
+
+
+@dataclass(frozen=True)
+class ArtifactState:
+    """State stored in .erk/state.toml tracking installed artifacts."""
+
+    version: str  # last full sync version (keep for backwards compat)
+    files: Mapping[str, ArtifactFileState]  # key: artifact path like "skills/dignified-python"
+
+
+@dataclass(frozen=True)
+class StalenessResult:
+    """Result of checking artifact staleness."""
+
+    is_stale: bool
+    reason: Literal["not-initialized", "version-mismatch", "up-to-date", "erk-repo"]
+    current_version: str
+    installed_version: str | None
+
+
+@dataclass(frozen=True)
+class OrphanCheckResult:
+    """Result of checking for orphaned artifacts."""
+
+    orphans: dict[str, list[str]]  # folder -> list of orphaned filenames
+    skipped_reason: Literal["erk-repo", "no-claude-dir", "no-bundled-dir"] | None
+
+
+@dataclass(frozen=True)
+class CompletenessCheckResult:
+    """Result of checking for missing bundled artifacts."""
+
+    missing: dict[str, list[str]]  # folder -> list of missing filenames
+    skipped_reason: Literal["erk-repo", "no-claude-dir", "no-bundled-dir"] | None

erk/artifacts/staleness.py

@@ -0,0 +1,56 @@
+"""Check artifact staleness by comparing installed vs current erk version."""
+
+from pathlib import Path
+
+from erk.artifacts.detection import is_in_erk_repo
+from erk.artifacts.models import StalenessResult
+from erk.artifacts.state import load_artifact_state
+from erk.core.release_notes import get_current_version
+
+
+def check_staleness(project_dir: Path) -> StalenessResult:
+    """Check if artifacts are stale compared to current erk version.
+
+    Returns a StalenessResult with:
+    - is_stale: True if artifacts need to be synced
+    - reason: "not-initialized", "version-mismatch", "up-to-date", or "erk-repo"
+    - current_version: The installed erk package version
+    - installed_version: The version artifacts were last synced from (or None)
+    """
+    current_version = get_current_version()
+
+    # In erk repo, artifacts are read from source - always up to date
+    # Still load state.toml to dogfood the state loading path
+    if is_in_erk_repo(project_dir):
+        state = load_artifact_state(project_dir)
+        return StalenessResult(
+            is_stale=False,
+            reason="erk-repo",
+            current_version=current_version,
+            installed_version=state.version if state else None,
+        )
+
+    state = load_artifact_state(project_dir)
+
+    if state is None:
+        return StalenessResult(
+            is_stale=True,
+            reason="not-initialized",
+            current_version=current_version,
+            installed_version=None,
+        )
+
+    if state.version != current_version:
+        return StalenessResult(
+            is_stale=True,
+            reason="version-mismatch",
+            current_version=current_version,
+            installed_version=state.version,
+        )
+
+    return StalenessResult(
+        is_stale=False,
+        reason="up-to-date",
+        current_version=current_version,
+        installed_version=state.version,
+    )

erk/artifacts/state.py

@@ -0,0 +1,100 @@
+"""Load and save artifact state from .erk/state.toml."""
+
+from pathlib import Path
+from typing import Any
+
+import tomli
+import tomli_w
+
+from erk.artifacts.models import ArtifactFileState, ArtifactState
+
+
+def _state_file_path(project_dir: Path) -> Path:
+    """Return path to state file."""
+    return project_dir / ".erk" / "state.toml"
+
+
+def load_artifact_state(project_dir: Path) -> ArtifactState | None:
+    """Load artifact state from .erk/state.toml.
+
+    Returns None if the state file doesn't exist, has no artifacts section,
+    or is missing the required files section.
+
+    Format:
+        [artifacts]
+        version = "0.3.1"
+
+        [artifacts.files."skills/dignified-python"]
+        version = "0.3.0"
+        hash = "a1b2c3d4e5f6g7h8"
+    """
+    path = _state_file_path(project_dir)
+    if not path.exists():
+        return None
+
+    with path.open("rb") as f:
+        data = tomli.load(f)
+
+    if "artifacts" not in data:
+        return None
+
+    artifacts_data = data["artifacts"]
+    if "version" not in artifacts_data:
+        return None
+
+    # Require files section
+    if "files" not in artifacts_data:
+        return None
+
+    files: dict[str, ArtifactFileState] = {}
+    files_data = artifacts_data["files"]
+
+    for artifact_path, file_data in files_data.items():
+        if isinstance(file_data, dict) and "version" in file_data and "hash" in file_data:
+            files[artifact_path] = ArtifactFileState(
+                version=file_data["version"],
+                hash=file_data["hash"],
+            )
+
+    return ArtifactState(version=artifacts_data["version"], files=files)
+
+
+def save_artifact_state(project_dir: Path, state: ArtifactState) -> None:
+    """Save artifact state to .erk/state.toml.
+
+    Creates the .erk/ directory and state.toml file if they don't exist.
+    Preserves other sections in the file if it already exists.
+
+    Format:
+        [artifacts]
+        version = "0.3.1"
+
+        [artifacts.files."skills/dignified-python"]
+        version = "0.3.0"
+        hash = "a1b2c3d4e5f6g7h8"
+    """
+    path = _state_file_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load existing data to preserve other sections
+    existing_data: dict[str, Any] = {}
+    if path.exists():
+        with path.open("rb") as f:
+            existing_data = tomli.load(f)
+
+    # Build files section
+    files_data: dict[str, dict[str, str]] = {}
+    for artifact_path, file_state in state.files.items():
+        files_data[artifact_path] = {
+            "version": file_state.version,
+            "hash": file_state.hash,
+        }
+
+    # Update artifacts section
+    existing_data["artifacts"] = {
+        "version": state.version,
+        "files": files_data,
+    }
+
+    with path.open("wb") as f:
+        tomli_w.dump(existing_data, f)