erk 0.4.5__py3-none-any.whl

erk/cli/commands/docs/sync.py

@@ -0,0 +1,121 @@
+"""Sync agent documentation index files.
+
+This command generates index.md files for docs/learned/ from frontmatter metadata.
+"""
+
+from pathlib import Path
+
+import click
+
+from erk.agent_docs.operations import sync_agent_docs
+from erk.cli.subprocess_utils import run_with_error_reporting
+
+
+@click.command(name="sync")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be done without writing files.",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Check if files are in sync without writing. Exit 1 if changes needed.",
+)
+def sync_command(*, dry_run: bool, check: bool) -> None:
+    """Regenerate index files from frontmatter.
+
+    Generates index.md files for:
+    - docs/learned/index.md (root index with categories and uncategorized docs)
+    - docs/learned/<category>/index.md (for categories with 2+ docs)
+
+    Index files are auto-generated and should not be manually edited.
+
+    Exit codes:
+    - 0: Sync completed successfully (or --check passes)
+    - 1: Error during sync (or --check finds files out of sync)
+    """
+    # --check implies dry-run behavior
+    effective_dry_run = dry_run or check
+
+    # Find repository root
+    result = run_with_error_reporting(
+        ["git", "rev-parse", "--show-toplevel"],
+        error_prefix="Failed to find repository root",
+        troubleshooting=["Ensure you're running from within a git repository"],
+    )
+    project_root = Path(result.stdout.strip())
+
+    if not project_root.exists():
+        click.echo(click.style("Error: Repository root not found", fg="red"), err=True)
+        raise SystemExit(1)
+
+    agent_docs_dir = project_root / "docs" / "learned"
+    if not agent_docs_dir.exists():
+        click.echo(click.style("No docs/learned/ directory found", fg="cyan"), err=True)
+        raise SystemExit(0)
+
+    # Sync index files
+    sync_result = sync_agent_docs(project_root, dry_run=effective_dry_run)
+
+    # Report results
+    if effective_dry_run:
+        click.echo(click.style("Dry run - no files written", fg="cyan", bold=True), err=True)
+        click.echo(err=True)
+
+    total_changes = len(sync_result.created) + len(sync_result.updated)
+
+    if sync_result.created:
+        action = "Would create" if effective_dry_run else "Created"
+        click.echo(f"{action} {len(sync_result.created)} file(s):", err=True)
+        for path in sync_result.created:
+            click.echo(f"  + {path}", err=True)
+        click.echo(err=True)
+
+    if sync_result.updated:
+        action = "Would update" if effective_dry_run else "Updated"
+        click.echo(f"{action} {len(sync_result.updated)} file(s):", err=True)
+        for path in sync_result.updated:
+            click.echo(f"  ~ {path}", err=True)
+        click.echo(err=True)
+
+    if sync_result.unchanged:
+        click.echo(f"Unchanged: {len(sync_result.unchanged)} file(s)", err=True)
+        click.echo(err=True)
+
+    # Report tripwires
+    if sync_result.tripwires_count > 0:
+        click.echo(f"Tripwires: {sync_result.tripwires_count} collected", err=True)
+        click.echo(err=True)
+
+    if sync_result.skipped_invalid > 0:
+        click.echo(
+            click.style(
+                f"Skipped {sync_result.skipped_invalid} doc(s) with invalid frontmatter",
+                fg="yellow",
+            ),
+            err=True,
+        )
+        click.echo("  Run 'erk docs validate' to see errors", err=True)
+        click.echo(err=True)
+
+    # Summary
+    if total_changes == 0 and sync_result.skipped_invalid == 0:
+        click.echo(click.style("All files are up to date", fg="green"), err=True)
+    elif total_changes > 0:
+        if check:
+            msg = f"Files out of sync: {total_changes} change(s) needed"
+            click.echo(click.style(msg, fg="red", bold=True), err=True)
+            click.echo(err=True)
+            click.echo("Run 'erk docs sync' to regenerate files from frontmatter.", err=True)
+            raise SystemExit(1)
+        elif effective_dry_run:
+            click.echo(
+                click.style(f"Would make {total_changes} change(s)", fg="cyan", bold=True),
+                err=True,
+            )
+        else:
+            click.echo(
+                click.style(f"Sync complete: {total_changes} change(s)", fg="green"),
+                err=True,
+            )

erk/cli/commands/docs/validate.py

@@ -0,0 +1,102 @@
+"""Validate agent documentation frontmatter.
+
+This command validates that all markdown files in docs/learned/ have valid
+frontmatter with required fields: title and read_when.
+"""
+
+import subprocess
+from pathlib import Path
+
+import click
+
+from erk.agent_docs.operations import validate_agent_docs
+
+
+@click.command(name="validate")
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show details for all files, not just errors.",
+)
+def validate_command(*, verbose: bool) -> None:
+    """Validate agent documentation frontmatter.
+
+    Checks that all markdown files in docs/learned/ have valid frontmatter:
+    - title: Human-readable document title
+    - read_when: List of conditions when agent should read this doc
+
+    Index files (index.md) are skipped as they are auto-generated.
+
+    Exit codes:
+    - 0: All files are valid
+    - 1: Validation errors found
+    """
+    # Find repository root
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    project_root = Path(result.stdout.strip())
+
+    if not project_root.exists():
+        click.echo(click.style("Error: Repository root not found", fg="red"), err=True)
+        raise SystemExit(1)
+
+    agent_docs_dir = project_root / "docs" / "learned"
+    if not agent_docs_dir.exists():
+        click.echo(click.style("No docs/learned/ directory found", fg="cyan"), err=True)
+        raise SystemExit(0)
+
+    # Validate all files
+    results = validate_agent_docs(project_root)
+
+    if len(results) == 0:
+        click.echo(click.style("No agent documentation files found", fg="cyan"), err=True)
+        raise SystemExit(0)
+
+    valid_count = sum(1 for r in results if r.is_valid)
+    invalid_count = len(results) - valid_count
+
+    # Show results
+    if verbose or invalid_count > 0:
+        for validation_result in results:
+            if validation_result.is_valid:
+                if verbose:
+                    status = click.style("OK", fg="green")
+                    click.echo(f"{status} {validation_result.file_path}", err=True)
+            else:
+                status = click.style("FAIL", fg="red")
+                click.echo(f"{status} {validation_result.file_path}", err=True)
+                for error in validation_result.errors:
+                    click.echo(f"    {error}", err=True)
+
+    # Summary
+    click.echo(err=True)
+    if invalid_count == 0:
+        click.echo(
+            click.style("Agent docs validation: PASSED", fg="green", bold=True),
+            err=True,
+        )
+        click.echo(err=True)
+        click.echo(f"Files validated: {len(results)}", err=True)
+        click.echo("All files have valid frontmatter!", err=True)
+    else:
+        click.echo(
+            click.style("Agent docs validation: FAILED", fg="red", bold=True),
+            err=True,
+        )
+        click.echo(err=True)
+        click.echo(f"Files validated: {len(results)}", err=True)
+        click.echo(f"  Valid: {valid_count}", err=True)
+        click.echo(f"  Invalid: {invalid_count}", err=True)
+        click.echo(err=True)
+        click.echo("Required frontmatter format:", err=True)
+        click.echo("  ---", err=True)
+        click.echo("  title: Document Title", err=True)
+        click.echo("  read_when:", err=True)
+        click.echo('    - "when to read this doc"', err=True)
+        click.echo("  ---", err=True)
+        raise SystemExit(1)

erk/cli/commands/doctor.py

@@ -0,0 +1,243 @@
+"""Doctor command for erk setup diagnostics.
+
+Runs health checks on the erk setup to identify issues with
+CLI availability, repository configuration, and Claude settings.
+"""
+
+import click
+
+from erk.core.context import ErkContext
+from erk.core.health_checks import CheckResult, run_all_checks
+from erk.core.health_checks_dogfooder import EARLY_DOGFOODER_CHECK_NAMES
+from erk_shared.hooks.logging import clear_hook_logs
+
+# Sub-group definitions for Repository Setup condensed display
+REPO_SUBGROUPS: dict[str, set[str]] = {
+    "Git repository": {"repository", "gitignore"},
+    "Claude settings": {
+        "claude-erk-permission",
+        "claude-settings",
+        "user-prompt-hook",
+        "exit-plan-hook",
+    },
+    "Erk configuration": {
+        "required-version",
+        "legacy-prompt-hooks",
+        "legacy-config",
+        "managed-artifacts",
+        "post-plan-implement-ci-hook",
+    },
+    "GitHub": {"workflow-permissions"},
+    "Hooks": {"hooks"},
+}
+
+# Sub-group definitions for User Setup condensed display
+USER_SUBGROUPS: dict[str, set[str]] = {
+    "User checks": {"github-auth", "claude-hooks", "statusline", "shell-integration"},
+}
+
+
+def _format_check_result(result: CheckResult, indent: str = "", verbose: bool = False) -> None:
+    """Format and display a single check result.
+
+    Args:
+        result: The check result to format
+        indent: Optional indentation prefix for nested display
+        verbose: If True and verbose_details exists, use it instead of details
+    """
+    if not result.passed:
+        icon = click.style("❌", fg="red")
+    elif result.warning:
+        icon = click.style("⚠️", fg="yellow")
+    elif result.info:
+        icon = click.style("ℹ️", fg="cyan")
+    else:
+        icon = click.style("✅", fg="green")
+
+    # Use verbose_details in verbose mode if available, otherwise use details
+    details = result.verbose_details if verbose and result.verbose_details else result.details
+
+    if details and "\n" not in details:
+        # Single-line details: show inline
+        styled_details = click.style(f" - {details}", dim=True)
+        click.echo(f"{indent}{icon} {result.message}{styled_details}")
+    else:
+        click.echo(f"{indent}{icon} {result.message}")
+        if details:
+            # Multi-line details: show with indentation
+            for line in details.split("\n"):
+                click.echo(click.style(f"{indent}   {line}", dim=True))
+
+
+def _format_subgroup(name: str, checks: list[CheckResult], verbose: bool, indent: str = "") -> None:
+    """Format a sub-group of checks (condensed or expanded).
+
+    Args:
+        name: Sub-group display name
+        checks: List of check results in this sub-group
+        verbose: If True, always show all individual checks
+        indent: Indentation prefix
+    """
+    if not checks:
+        return
+
+    passed = sum(1 for c in checks if c.passed)
+    total = len(checks)
+    all_passed = passed == total
+
+    if verbose:
+        # Always show all individual checks with sub-group header
+        click.echo(click.style(f"{indent}  {name}", dim=True))
+        for result in checks:
+            _format_check_result(result, indent=f"{indent}  ", verbose=True)
+    elif all_passed:
+        # Condensed: single line with count
+        icon = click.style("✅", fg="green")
+        click.echo(f"{indent}{icon} {name} ({total} checks)")
+    else:
+        # Failed: show summary line + expand failures
+        icon = click.style("❌", fg="red")
+        click.echo(f"{indent}{icon} {name} ({passed}/{total} checks)")
+        for result in checks:
+            if not result.passed:
+                _format_check_result(result, indent=f"{indent}   ", verbose=False)
+
+
+@click.command("doctor")
+@click.option("-v", "--verbose", is_flag=True, help="Show all individual checks")
+@click.option("--dogfooder", is_flag=True, help="Include early dogfooder migration checks")
+@click.option(
+    "--clear-hook-logs", "clear_hook_logs_flag", is_flag=True, help="Clear all hook execution logs"
+)
+@click.pass_obj
+def doctor_cmd(ctx: ErkContext, verbose: bool, dogfooder: bool, clear_hook_logs_flag: bool) -> None:
+    """Run diagnostic checks on erk setup.
+
+    Checks for:
+
+    \b
+      - Repository Setup: git config, Claude settings, erk config, hooks
+      - User Setup: prerequisites (erk, claude, gt, gh, uv), GitHub auth
+
+    Examples:
+
+    \b
+      # Run checks (condensed output)
+      erk doctor
+
+      # Show all individual checks
+      erk doctor --verbose
+
+      # Include early dogfooder migration checks
+      erk doctor --dogfooder
+
+      # Clear hook execution logs
+      erk doctor --clear-hook-logs
+    """
+    # Handle --clear-hook-logs flag (clears logs and returns early)
+    if clear_hook_logs_flag:
+        deleted_count = clear_hook_logs(ctx.repo_root)
+        click.echo(f"Cleared {deleted_count} hook log(s)")
+        return
+
+    click.echo(click.style("🔍 Checking erk setup...", bold=True))
+    click.echo("")
+
+    # Run all checks
+    results = run_all_checks(ctx)
+
+    # Group results by category
+    prerequisite_names = {"erk", "claude", "graphite", "github", "uv"}
+    user_check_names = {"github-auth", "claude-hooks", "statusline", "shell-integration"}
+    repo_check_names = {
+        "repository",
+        "claude-settings",
+        "user-prompt-hook",
+        "exit-plan-hook",
+        "gitignore",
+        "claude-erk-permission",
+        "legacy-config",
+        "required-version",
+        "legacy-prompt-hooks",
+        "managed-artifacts",
+        "post-plan-implement-ci-hook",
+        "workflow-permissions",
+        "hooks",
+    }
+
+    prerequisite_checks = [r for r in results if r.name in prerequisite_names]
+    user_checks = [r for r in results if r.name in user_check_names]
+    repo_checks = [r for r in results if r.name in repo_check_names]
+    early_dogfooder_checks = [r for r in results if r.name in EARLY_DOGFOODER_CHECK_NAMES]
+
+    # Track displayed check names to catch any uncategorized checks
+    displayed_names = (
+        prerequisite_names | user_check_names | repo_check_names | EARLY_DOGFOODER_CHECK_NAMES
+    )
+
+    # Display Repository Setup FIRST (with sub-groups)
+    click.echo(click.style("Repository Setup", bold=True))
+    if verbose:
+        # In verbose mode, show sub-groups with all individual checks
+        for subgroup_name, subgroup_check_names in REPO_SUBGROUPS.items():
+            subgroup_checks = [r for r in repo_checks if r.name in subgroup_check_names]
+            _format_subgroup(subgroup_name, subgroup_checks, verbose=True)
+    else:
+        # Condensed mode: show sub-group summaries
+        for subgroup_name, subgroup_check_names in REPO_SUBGROUPS.items():
+            subgroup_checks = [r for r in repo_checks if r.name in subgroup_check_names]
+            _format_subgroup(subgroup_name, subgroup_checks, verbose=False)
+    click.echo("")
+
+    # Display Early Dogfooder checks (only when --dogfooder flag is passed)
+    if dogfooder and early_dogfooder_checks:
+        click.echo(click.style("Early Dogfooder", bold=True))
+        for result in early_dogfooder_checks:
+            _format_check_result(result, verbose=verbose)
+        click.echo("")
+
+    # Display User Setup SECOND
+    click.echo(click.style("User Setup", bold=True))
+    # Prerequisites (always expanded)
+    for result in prerequisite_checks:
+        _format_check_result(result, verbose=verbose)
+    # User checks (condensable subgroup)
+    if verbose:
+        for subgroup_name, subgroup_check_names in USER_SUBGROUPS.items():
+            subgroup_checks = [r for r in user_checks if r.name in subgroup_check_names]
+            _format_subgroup(subgroup_name, subgroup_checks, verbose=True)
+    else:
+        for subgroup_name, subgroup_check_names in USER_SUBGROUPS.items():
+            subgroup_checks = [r for r in user_checks if r.name in subgroup_check_names]
+            _format_subgroup(subgroup_name, subgroup_checks, verbose=False)
+    click.echo("")
+
+    # Display any uncategorized checks (defensive - catches missing categorization)
+    other_checks = [r for r in results if r.name not in displayed_names]
+    if other_checks:
+        click.echo(click.style("Other Checks", bold=True))
+        for result in other_checks:
+            _format_check_result(result, verbose=verbose)
+        click.echo("")
+
+    # Collect and display consolidated remediations for failing checks
+    remediations = {r.remediation for r in results if r.remediation and not r.passed}
+    if remediations:
+        click.echo(click.style("Remediation", bold=True))
+        for remediation in sorted(remediations):
+            click.echo(f"  {remediation}")
+        click.echo("")
+
+    # Calculate summary - exclude dogfooder checks from total if not showing them
+    checks_for_summary = [r for r in results if r.name not in EARLY_DOGFOODER_CHECK_NAMES]
+    if dogfooder:
+        checks_for_summary = results
+
+    passed = sum(1 for r in checks_for_summary if r.passed)
+    total = len(checks_for_summary)
+    failed = total - passed
+
+    if failed == 0:
+        click.echo(click.style("✨ All checks passed!", fg="green", bold=True))
+    else:
+        click.echo(click.style(f"⚠️  {failed} check(s) failed", fg="yellow", bold=True))

erk/cli/commands/down.py

@@ -0,0 +1,171 @@
+import click
+
+from erk.cli.commands.navigation_helpers import (
+    activate_root_repo,
+    activate_worktree,
+    check_clean_working_tree,
+    check_pending_extraction_marker,
+    render_activation_script,
+    resolve_down_navigation,
+    unallocate_worktree_and_branch,
+    verify_pr_closed_or_merged,
+)
+from erk.cli.core import discover_repo_context
+from erk.cli.ensure import Ensure
+from erk.cli.graphite_command import GraphiteCommandWithHiddenOptions
+from erk.cli.help_formatter import script_option
+from erk.core.context import ErkContext
+from erk.core.worktree_utils import compute_relative_path_in_worktree
+from erk_shared.output.output import machine_output, user_output
+
+
+@click.command("down", cls=GraphiteCommandWithHiddenOptions)
+@script_option
+@click.option(
+    "--delete-current",
+    is_flag=True,
+    help="Delete current branch and worktree after navigating down",
+)
+@click.option(
+    "-f",
+    "--force",
+    is_flag=True,
+    help="Force deletion even if marker exists or PR is open (prompts)",
+)
+@click.pass_obj
+def down_cmd(ctx: ErkContext, script: bool, delete_current: bool, force: bool) -> None:
+    """Move to parent branch in worktree stack.
+
+    With shell integration (recommended):
+      erk down
+
+    The shell wrapper function automatically activates the worktree.
+    Run 'erk init --shell' to set up shell integration.
+
+    Without shell integration:
+      source <(erk down --script)
+
+    This will cd to the parent branch's worktree (or root repo if parent is trunk),
+    create/activate .venv, and load .env variables.
+    Requires Graphite to be enabled: 'erk config set use_graphite true'
+    """
+    # Validate preconditions upfront (LBYL)
+    Ensure.gh_authenticated(ctx)
+
+    repo = discover_repo_context(ctx, ctx.cwd)
+    trunk_branch = ctx.trunk_branch
+
+    # Get current branch
+    current_branch = Ensure.not_none(
+        ctx.git.get_current_branch(ctx.cwd), "Not currently on a branch (detached HEAD)"
+    )
+
+    # Store current worktree path for deletion (before navigation)
+    # Find the worktree for the current branch
+    current_worktree_path = None
+    if delete_current:
+        current_worktree_path = Ensure.not_none(
+            ctx.git.find_worktree_for_branch(repo.root, current_branch),
+            f"Cannot find worktree for current branch '{current_branch}'.",
+        )
+
+    # Safety checks before navigation (if --delete-current flag is set)
+    if delete_current and current_worktree_path is not None:
+        check_clean_working_tree(ctx)
+        verify_pr_closed_or_merged(ctx, repo.root, current_branch, force)
+        # Check for pending extraction marker
+        check_pending_extraction_marker(current_worktree_path, force)
+
+    # Get all worktrees for checking if target has a worktree
+    worktrees = ctx.git.list_worktrees(repo.root)
+
+    # Resolve navigation to get target branch or 'root' (may auto-create worktree)
+    target_name, was_created = resolve_down_navigation(
+        ctx, repo, current_branch, worktrees, trunk_branch
+    )
+
+    # Show creation message if worktree was just created
+    if was_created and not script:
+        user_output(
+            click.style("✓", fg="green")
+            + f" Created worktree for {click.style(target_name, fg='yellow')} and moved to it"
+        )
+
+    # Check if target_name refers to 'root' which means root repo
+    if target_name == "root":
+        if delete_current and current_worktree_path is not None:
+            # Handle activation inline so we can do cleanup before exiting
+            root_path = repo.root
+            if script:
+                script_content = render_activation_script(
+                    worktree_path=root_path,
+                    target_subpath=compute_relative_path_in_worktree(worktrees, ctx.cwd),
+                    post_cd_commands=None,
+                    final_message='echo "Went to root repo: $(pwd)"',
+                    comment="work activate-script (root repo)",
+                )
+                result = ctx.script_writer.write_activation_script(
+                    script_content,
+                    command_name="down",
+                    comment="activate root",
+                )
+                machine_output(str(result.path), nl=False)
+            else:
+                user_output(f"Went to root repo: {root_path}")
+
+            # Perform cleanup (no context regeneration needed - we haven't changed dirs)
+            unallocate_worktree_and_branch(ctx, repo, current_branch, current_worktree_path)
+
+            # Exit after cleanup
+            raise SystemExit(0)
+        else:
+            # No cleanup needed, use standard activation
+            activate_root_repo(ctx, repo, script, "down", post_cd_commands=None)
+
+    # Resolve target branch to actual worktree path
+    target_wt_path = Ensure.not_none(
+        ctx.git.find_worktree_for_branch(repo.root, target_name),
+        f"Branch '{target_name}' has no worktree. This should not happen.",
+    )
+
+    if delete_current and current_worktree_path is not None:
+        # Handle activation inline so we can do cleanup before exiting
+        Ensure.path_exists(ctx, target_wt_path, f"Worktree not found: {target_wt_path}")
+
+        if script:
+            activation_script = render_activation_script(
+                worktree_path=target_wt_path,
+                target_subpath=compute_relative_path_in_worktree(worktrees, ctx.cwd),
+                post_cd_commands=None,
+                final_message='echo "Activated worktree: $(pwd)"',
+                comment="work activate-script",
+            )
+            result = ctx.script_writer.write_activation_script(
+                activation_script,
+                command_name="down",
+                comment=f"activate {target_wt_path.name}",
+            )
+            machine_output(str(result.path), nl=False)
+        else:
+            user_output(
+                "Shell integration not detected. "
+                "Run 'erk init --shell' to set up automatic activation."
+            )
+            user_output("\nOr use: source <(erk down --script)")
+
+        # Perform cleanup (no context regeneration needed - we haven't actually changed directories)
+        unallocate_worktree_and_branch(ctx, repo, current_branch, current_worktree_path)
+
+        # Exit after cleanup
+        raise SystemExit(0)
+    else:
+        # No cleanup needed, use standard activation
+        activate_worktree(
+            ctx=ctx,
+            repo=repo,
+            target_path=target_wt_path,
+            script=script,
+            command_name="down",
+            preserve_relative_path=True,
+            post_cd_commands=None,
+        )

erk/cli/commands/exec/__init__.py

@@ -0,0 +1 @@
+"""Static exec group for erk scripts."""