erk 0.4.5__py3-none-any.whl

erk/cli/commands/artifact/check.py

@@ -0,0 +1,260 @@
+"""Check artifact sync status."""
+
+from pathlib import Path
+
+import click
+
+from erk.artifacts.artifact_health import (
+    ArtifactStatus,
+    find_missing_artifacts,
+    find_orphaned_artifacts,
+    get_artifact_health,
+    is_erk_managed,
+)
+from erk.artifacts.discovery import discover_artifacts
+from erk.artifacts.models import InstalledArtifact
+from erk.artifacts.staleness import check_staleness
+from erk.artifacts.state import load_artifact_state
+
+
+def _display_orphan_warnings(orphans: dict[str, list[str]]) -> None:
+    """Display orphan warnings with remediation commands."""
+    total_orphans = sum(len(files) for files in orphans.values())
+    click.echo(click.style("⚠️  ", fg="yellow") + f"Found {total_orphans} orphaned artifact(s)")
+    click.echo("   Orphaned files (not in current erk package):")
+    for folder, files in sorted(orphans.items()):
+        click.echo(f"     {folder}/:")
+        for filename in sorted(files):
+            click.echo(f"       - {filename}")
+
+    click.echo("")
+    click.echo("   To remove:")
+    for folder, files in sorted(orphans.items()):
+        for filename in sorted(files):
+            # Workflows are in .github/, not .claude/
+            if folder.startswith(".github"):
+                click.echo(f"     rm {folder}/{filename}")
+            else:
+                click.echo(f"     rm .claude/{folder}/{filename}")
+
+
+def _display_missing_warnings(missing: dict[str, list[str]]) -> None:
+    """Display missing artifact warnings."""
+    total_missing = sum(len(files) for files in missing.values())
+    click.echo(click.style("⚠️  ", fg="yellow") + f"Found {total_missing} missing artifact(s)")
+    click.echo("   Missing from project:")
+    for folder, files in sorted(missing.items()):
+        click.echo(f"     {folder}:")
+        for filename in sorted(files):
+            click.echo(f"       - {filename}")
+    click.echo("")
+    click.echo("   Run 'erk artifact sync' to install missing artifacts")
+
+
+def _format_artifact_path(artifact: InstalledArtifact) -> str:
+    """Format artifact as a display path string."""
+    if artifact.artifact_type == "command":
+        # Commands can be namespaced (local:foo) or top-level (foo)
+        if ":" in artifact.name:
+            namespace, name = artifact.name.split(":", 1)
+            return f"commands/{namespace}/{name}.md"
+        return f"commands/{artifact.name}.md"
+    if artifact.artifact_type == "skill":
+        return f"skills/{artifact.name}"
+    if artifact.artifact_type == "agent":
+        return f"agents/{artifact.name}"
+    if artifact.artifact_type == "workflow":
+        return f".github/workflows/{artifact.name}.yml"
+    if artifact.artifact_type == "hook":
+        return f"hooks/{artifact.name} (settings.json)"
+    return artifact.name
+
+
+def _display_installed_artifacts(project_dir: Path) -> None:
+    """Display list of artifacts actually installed in project."""
+    artifacts = discover_artifacts(project_dir)
+
+    if not artifacts:
+        click.echo("   (no artifacts installed)")
+        return
+
+    for artifact in artifacts:
+        suffix = "" if is_erk_managed(artifact) else " (unmanaged)"
+        click.echo(f"   {_format_artifact_path(artifact)}{suffix}")
+
+
+def _format_artifact_status(artifact: ArtifactStatus, show_hashes: bool) -> str:
+    """Format artifact status for verbose output.
+
+    Args:
+        artifact: The artifact status to format
+        show_hashes: If True, show hash comparison details
+    """
+    if artifact.status == "up-to-date":
+        icon = click.style("✓", fg="green")
+        detail = f"{artifact.current_version} (up-to-date)"
+    elif artifact.status == "changed-upstream":
+        icon = click.style("⚠", fg="yellow")
+        if artifact.installed_version:
+            detail = f"{artifact.installed_version} → {artifact.current_version} (changed upstream)"
+        else:
+            detail = f"→ {artifact.current_version} (new in this version)"
+    elif artifact.status == "locally-modified":
+        icon = click.style("⚠", fg="yellow")
+        detail = f"{artifact.current_version} (locally modified)"
+    else:  # not-installed
+        icon = click.style("✗", fg="red")
+        detail = "(not installed)"
+
+    lines = [f"  {icon} {artifact.name}: {detail}"]
+
+    if show_hashes:
+        # Show state.toml values
+        if artifact.installed_version is not None and artifact.installed_hash is not None:
+            ver = artifact.installed_version
+            h = artifact.installed_hash
+            lines.append(f"       state.toml: version={ver}, hash={h}")
+        else:
+            lines.append("       state.toml: (not tracked)")
+
+        # Show current source values
+        if artifact.current_hash is not None:
+            ver = artifact.current_version
+            h = artifact.current_hash
+            lines.append(f"       source:     version={ver}, hash={h}")
+        else:
+            lines.append("       source:     (not installed)")
+
+    return "\n".join(lines)
+
+
+def _display_verbose_status(project_dir: Path, show_hashes: bool) -> bool:
+    """Display per-artifact status breakdown.
+
+    Shows two sections:
+    1. Erk-managed artifacts with version tracking status
+    2. Project artifacts (local commands, custom skills, etc.)
+
+    Args:
+        project_dir: Path to the project root
+        show_hashes: If True, show hash comparison details for each artifact
+
+    Returns True if any erk-managed artifacts need attention (not up-to-date).
+    """
+    state = load_artifact_state(project_dir)
+    saved_files = dict(state.files) if state else {}
+
+    health_result = get_artifact_health(project_dir, saved_files)
+
+    if health_result.skipped_reason is not None:
+        return False
+
+    click.echo("")
+    click.echo("Erk-managed artifacts:")
+
+    has_issues = False
+    for artifact in health_result.artifacts:
+        click.echo(_format_artifact_status(artifact, show_hashes))
+        if artifact.status != "up-to-date":
+            has_issues = True
+
+    # Also show project-specific artifacts (non-erk-managed)
+    all_artifacts = discover_artifacts(project_dir)
+    project_artifacts = [a for a in all_artifacts if not is_erk_managed(a)]
+
+    if project_artifacts:
+        click.echo("")
+        click.echo("Project artifacts (unmanaged):")
+        for artifact in project_artifacts:
+            click.echo(f"   {_format_artifact_path(artifact)}")
+
+    return has_issues
+
+
+@click.command("check")
+@click.option(
+    "--verbose",
+    "-v",
+    count=True,
+    help="Show per-artifact status. Use -vv to also show hash comparisons.",
+)
+def check_cmd(verbose: int) -> None:
+    """Check if artifacts are in sync with erk version.
+
+    Compares the version recorded in .erk/state.toml against
+    the currently installed erk package version. Also checks
+    for orphaned files that should be removed.
+
+    Examples:
+
+    \b
+      # Check sync status
+      erk artifact check
+
+    \b
+      # Show per-artifact breakdown
+      erk artifact check -v
+
+    \b
+      # Show hash comparisons (state.toml vs source)
+      erk artifact check -vv
+    """
+    project_dir = Path.cwd()
+
+    staleness_result = check_staleness(project_dir)
+    orphan_result = find_orphaned_artifacts(project_dir)
+    missing_result = find_missing_artifacts(project_dir)
+
+    has_errors = False
+    show_per_artifact = verbose >= 1
+    show_hashes = verbose >= 2
+
+    # Check staleness
+    if staleness_result.reason == "erk-repo":
+        click.echo(click.style("✓ ", fg="green") + "Development mode (artifacts read from source)")
+        if not show_per_artifact:
+            _display_installed_artifacts(project_dir)
+    elif staleness_result.reason == "not-initialized":
+        click.echo(click.style("⚠️  ", fg="yellow") + "Artifacts not initialized")
+        click.echo(f"   Current erk version: {staleness_result.current_version}")
+        click.echo("   Run 'erk artifact sync' to initialize")
+        has_errors = True
+    elif staleness_result.reason == "version-mismatch":
+        click.echo(click.style("⚠️  ", fg="yellow") + "Artifacts out of sync")
+        click.echo(f"   Installed version: {staleness_result.installed_version}")
+        click.echo(f"   Current erk version: {staleness_result.current_version}")
+        click.echo("   Run 'erk artifact sync' to update")
+        has_errors = True
+    else:
+        click.echo(
+            click.style("✓ ", fg="green")
+            + f"Artifacts up to date (v{staleness_result.current_version})"
+        )
+        if not show_per_artifact:
+            _display_installed_artifacts(project_dir)
+
+    # Show verbose per-artifact breakdown if requested
+    if show_per_artifact and staleness_result.reason != "not-initialized":
+        verbose_has_issues = _display_verbose_status(project_dir, show_hashes)
+        # In dev mode (erk-repo), don't report issues - artifacts come from source
+        if verbose_has_issues and staleness_result.reason != "erk-repo":
+            has_errors = True
+
+    # Check for orphans (skip if erk-repo or no-claude-dir)
+    if orphan_result.skipped_reason is None:
+        if orphan_result.orphans:
+            _display_orphan_warnings(orphan_result.orphans)
+            has_errors = True
+        else:
+            click.echo(click.style("✓ ", fg="green") + "No orphaned artifacts")
+
+    # Check for missing artifacts (skip if erk-repo or no-claude-dir)
+    if missing_result.skipped_reason is None:
+        if missing_result.missing:
+            _display_missing_warnings(missing_result.missing)
+            has_errors = True
+        else:
+            click.echo(click.style("✓ ", fg="green") + "No missing artifacts")
+
+    if has_errors:
+        raise SystemExit(1)

erk/cli/commands/artifact/group.py

@@ -0,0 +1,31 @@
+"""Artifact command group for managing .claude/ artifacts."""
+
+import click
+
+from erk.cli.commands.artifact.check import check_cmd
+from erk.cli.commands.artifact.list_cmd import list_cmd
+from erk.cli.commands.artifact.show import show_cmd
+from erk.cli.commands.artifact.sync_cmd import sync_cmd
+
+
+@click.group(name="artifact")
+def artifact_group() -> None:
+    """Manage erk-managed artifacts.
+
+    Artifacts are Claude Code extensions like skills, commands, agents,
+    and workflows stored in your project's .claude/ and .github/ directories.
+
+    \b
+    Commands:
+      list   List installed artifacts
+      show   Display artifact content
+      sync   Sync artifacts from erk package
+      check  Check if artifacts are up to date
+    """
+
+
+# Register subcommands
+artifact_group.add_command(list_cmd)
+artifact_group.add_command(show_cmd)
+artifact_group.add_command(sync_cmd)
+artifact_group.add_command(check_cmd)

erk/cli/commands/artifact/list_cmd.py

@@ -0,0 +1,89 @@
+"""List artifacts installed in the project."""
+
+from pathlib import Path
+from typing import cast
+
+import click
+
+from erk.artifacts.artifact_health import is_erk_managed
+from erk.artifacts.discovery import discover_artifacts
+from erk.artifacts.models import ArtifactType
+
+
+@click.command("list")
+@click.option(
+    "--type",
+    "artifact_type",
+    type=click.Choice(["skill", "command", "agent", "workflow", "hook"]),
+    help="Filter by artifact type",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Show additional details")
+def list_cmd(artifact_type: str | None, verbose: bool) -> None:
+    """List all artifacts in project.
+
+    Examples:
+
+    \b
+      # List all artifacts
+      erk artifact list
+
+    \b
+      # List only skills
+      erk artifact list --type skill
+
+    \b
+      # List with details
+      erk artifact list --verbose
+    """
+    project_dir = Path.cwd()
+    claude_dir = project_dir / ".claude"
+    if not claude_dir.exists():
+        click.echo("No .claude/ directory found in current directory", err=True)
+        raise SystemExit(1)
+
+    artifacts = discover_artifacts(project_dir)
+
+    # Filter by type if specified
+    if artifact_type is not None:
+        assert artifact_type in ("skill", "command", "agent", "workflow", "hook")
+        typed_filter = cast(ArtifactType, artifact_type)
+        artifacts = [a for a in artifacts if a.artifact_type == typed_filter]
+
+    if not artifacts:
+        if artifact_type:
+            click.echo(f"No {artifact_type} artifacts found")
+        else:
+            click.echo("No artifacts found")
+        return
+
+    # Group by type for display
+    current_type: str | None = None
+    for artifact in artifacts:
+        if artifact.artifact_type != current_type:
+            if current_type is not None:
+                click.echo("")  # Blank line between types
+            current_type = artifact.artifact_type
+            # Special headers for types with non-standard locations/display
+            if current_type == "workflow":
+                header = "Github Workflows (.github/workflows):"
+            elif current_type == "hook":
+                header = "Hooks (.claude/settings.json):"
+            else:
+                # Capitalize first letter only (e.g., "Commands:")
+                header = current_type.capitalize() + "s:"
+            click.echo(click.style(header, bold=True))
+
+        # Format badge based on management status
+        is_managed = is_erk_managed(artifact)
+        if is_managed:
+            badge = click.style(" [erk]", fg="cyan")
+        else:
+            badge = click.style(" [unmanaged]", fg="yellow")
+
+        if verbose:
+            click.echo(f"    {artifact.name}{badge}")
+            click.echo(click.style(f"      Path: {artifact.path}", dim=True))
+            if is_managed and artifact.content_hash:
+                click.echo(click.style(f"      Hash: {artifact.content_hash}", dim=True))
+        else:
+            click.echo(f"    {artifact.name}{badge}")

erk/cli/commands/artifact/show.py

@@ -0,0 +1,62 @@
+"""Show artifact content."""
+
+from pathlib import Path
+from typing import cast
+
+import click
+
+from erk.artifacts.discovery import get_artifact_by_name
+from erk.artifacts.models import ArtifactType
+
+
+@click.command("show")
+@click.argument("name")
+@click.option(
+    "--type",
+    "artifact_type",
+    type=click.Choice(["skill", "command", "agent", "workflow"]),
+    help="Artifact type (optional, helps disambiguate)",
+)
+def show_cmd(name: str, artifact_type: str | None) -> None:
+    """Display the content of an artifact.
+
+    Examples:
+
+    \b
+      # Show a skill
+      erk artifact show dignified-python
+
+    \b
+      # Show a command (use colon for namespaced commands)
+      erk artifact show erk:plan-implement
+
+    \b
+      # Disambiguate by type
+      erk artifact show my-artifact --type skill
+    """
+    project_dir = Path.cwd()
+    claude_dir = project_dir / ".claude"
+    if not claude_dir.exists():
+        click.echo("No .claude/ directory found in current directory", err=True)
+        raise SystemExit(1)
+
+    type_filter: ArtifactType | None = None
+    if artifact_type is not None:
+        assert artifact_type in ("skill", "command", "agent", "workflow")
+        type_filter = cast(ArtifactType, artifact_type)
+
+    artifact = get_artifact_by_name(project_dir, name, type_filter)
+
+    if artifact is None:
+        click.echo(f"Artifact not found: {name}", err=True)
+        raise SystemExit(1)
+
+    # Display metadata
+    click.echo(click.style(f"# {artifact.name}", bold=True))
+    click.echo(click.style(f"Type: {artifact.artifact_type}", dim=True))
+    click.echo(click.style(f"Path: {artifact.path}", dim=True))
+    click.echo("")
+
+    # Display content
+    content = artifact.path.read_text(encoding="utf-8")
+    click.echo(content)

erk/cli/commands/artifact/sync_cmd.py

@@ -0,0 +1,39 @@
+"""Sync artifacts from erk package to project."""
+
+from pathlib import Path
+
+import click
+
+from erk.artifacts.sync import sync_artifacts
+
+
+@click.command("sync")
+@click.option("-f", "--force", is_flag=True, help="Force sync even if up to date")
+def sync_cmd(force: bool) -> None:
+    """Sync artifacts from erk package to .claude/ directory.
+
+    Copies bundled artifacts (commands, skills, agents, docs) from the
+    installed erk package to the current project's .claude/ directory.
+
+    When running in the erk repo itself, this is a no-op since artifacts
+    are read directly from source.
+
+    Examples:
+
+    \b
+      # Sync artifacts
+      erk artifact sync
+
+    \b
+      # Force re-sync even if up to date
+      erk artifact sync --force
+    """
+    project_dir = Path.cwd()
+
+    result = sync_artifacts(project_dir, force)
+
+    if result.success:
+        click.echo(click.style("✓ ", fg="green") + result.message)
+    else:
+        click.echo(click.style("✗ ", fg="red") + result.message, err=True)
+        raise SystemExit(1)

erk/cli/commands/branch/__init__.py

@@ -0,0 +1,26 @@
+"""Branch management commands."""
+
+import click
+
+from erk.cli.alias import alias, register_with_aliases
+from erk.cli.commands.branch.assign_cmd import branch_assign
+from erk.cli.commands.branch.checkout_cmd import branch_checkout
+from erk.cli.commands.branch.create_cmd import branch_create
+from erk.cli.commands.branch.list_cmd import branch_list
+from erk.cli.commands.branch.unassign_cmd import branch_unassign
+from erk.cli.help_formatter import ErkCommandGroup
+
+
+@alias("br")
+@click.group("branch", cls=ErkCommandGroup, grouped=False)
+def branch_group() -> None:
+    """Manage branches."""
+    pass
+
+
+# Register subcommands
+branch_group.add_command(branch_create)
+branch_group.add_command(branch_assign)
+branch_group.add_command(branch_unassign)
+register_with_aliases(branch_group, branch_checkout)
+register_with_aliases(branch_group, branch_list)

erk/cli/commands/branch/assign_cmd.py

@@ -0,0 +1,152 @@
+"""Branch assign command - assign an existing branch to a worktree slot."""
+
+import sys
+from datetime import UTC, datetime
+
+import click
+
+from erk.cli.commands.slot.common import (
+    cleanup_worktree_artifacts,
+    find_branch_assignment,
+    find_next_available_slot,
+    generate_slot_name,
+    get_pool_size,
+    handle_pool_full_interactive,
+)
+from erk.cli.core import discover_repo_context
+from erk.cli.ensure import Ensure
+from erk.core.context import ErkContext
+from erk.core.repo_discovery import ensure_erk_metadata_dir
+from erk.core.worktree_pool import (
+    PoolState,
+    SlotAssignment,
+    load_pool_state,
+    save_pool_state,
+)
+from erk_shared.output.output import user_output
+
+
+@click.command("assign")
+@click.argument("branch_name", metavar="BRANCH")
+@click.option("-f", "--force", is_flag=True, help="Auto-unassign oldest branch if pool is full")
+@click.pass_obj
+def branch_assign(ctx: ErkContext, branch_name: str, force: bool) -> None:
+    """Assign an EXISTING branch to an available pool slot.
+
+    BRANCH is the name of an existing git branch to assign to the pool.
+
+    The command will:
+    1. Verify the branch EXISTS (fails if it doesn't)
+    2. Find the next available slot in the pool
+    3. Create a worktree for that slot if needed
+    4. Assign the branch to the slot
+    5. Persist the assignment to pool.json
+
+    Use `erk br create` to create a NEW branch and assign it.
+    """
+    repo = discover_repo_context(ctx, ctx.cwd)
+    ensure_erk_metadata_dir(repo)
+
+    # Get pool size from config or default
+    pool_size = get_pool_size(ctx)
+
+    # Load or create pool state
+    state = load_pool_state(repo.pool_json_path)
+    if state is None:
+        state = PoolState(
+            version="1.0",
+            pool_size=pool_size,
+            slots=(),
+            assignments=(),
+        )
+
+    # Check if branch is already assigned
+    existing = find_branch_assignment(state, branch_name)
+    if existing is not None:
+        user_output(f"Error: Branch '{branch_name}' already assigned to {existing.slot_name}")
+        raise SystemExit(1) from None
+
+    # Check if branch exists - assign command requires EXISTING branch
+    local_branches = ctx.git.list_local_branches(repo.root)
+    if branch_name not in local_branches:
+        user_output(
+            f"Error: Branch '{branch_name}' does not exist.\n"
+            "Use `erk br create` to create a new branch."
+        )
+        raise SystemExit(1) from None
+
+    # Find next available slot
+    slot_num = find_next_available_slot(state, repo.worktrees_dir)
+    if slot_num is None:
+        # Pool is full - handle interactively or with --force
+        to_unassign = handle_pool_full_interactive(state, force, sys.stdin.isatty())
+        if to_unassign is None:
+            raise SystemExit(1) from None
+
+        # Remove the assignment from state
+        new_assignments = tuple(
+            a for a in state.assignments if a.slot_name != to_unassign.slot_name
+        )
+        state = PoolState(
+            version=state.version,
+            pool_size=state.pool_size,
+            slots=state.slots,
+            assignments=new_assignments,
+        )
+        save_pool_state(repo.pool_json_path, state)
+        user_output(
+            click.style("✓ ", fg="green")
+            + f"Unassigned {click.style(to_unassign.branch_name, fg='yellow')} "
+            + f"from {click.style(to_unassign.slot_name, fg='cyan')}"
+        )
+
+        # Use the slot we just unassigned (it has a worktree directory that can be reused)
+        slot_name = to_unassign.slot_name
+        worktree_path = to_unassign.worktree_path
+    else:
+        slot_name = generate_slot_name(slot_num)
+        worktree_path = repo.worktrees_dir / slot_name
+
+    # Create worktree if it doesn't exist
+    if not ctx.git.path_exists(worktree_path):
+        # Create directory for worktree
+        worktree_path.mkdir(parents=True, exist_ok=True)
+
+        # Add worktree
+        ctx.git.add_worktree(
+            repo.root,
+            worktree_path,
+            branch=branch_name,
+            ref=None,
+            create_branch=False,
+        )
+    else:
+        # Worktree exists - clean up stale artifacts and check out the branch
+        Ensure.invariant(
+            ctx.git.is_dir(worktree_path),
+            f"Expected {worktree_path} to be a directory",
+        )
+        cleanup_worktree_artifacts(worktree_path)
+        ctx.git.checkout_branch(worktree_path, branch_name)
+
+    # Create new assignment
+    now = datetime.now(UTC).isoformat()
+    new_assignment = SlotAssignment(
+        slot_name=slot_name,
+        branch_name=branch_name,
+        assigned_at=now,
+        worktree_path=worktree_path,
+    )
+
+    # Update state with new assignment
+    new_state = PoolState(
+        version=state.version,
+        pool_size=state.pool_size,
+        slots=state.slots,
+        assignments=(*state.assignments, new_assignment),
+    )
+
+    # Save state
+    save_pool_state(repo.pool_json_path, new_state)
+
+    user_output(click.style(f"✓ Assigned {branch_name} to {slot_name}", fg="green"))