"""LearnedDocsCapability - agent-discoverable documentation system."""

from pathlib import Path

from erk.core.capabilities.base import (
    Capability,
    CapabilityArtifact,
    CapabilityResult,
    CapabilityScope,
    ManagedArtifact,
)

LEARNED_DOCS_README = """\
---
title: "Learned Documentation Guide"
read_when:
  - "setting up learned docs"
  - "understanding learned docs structure"
  - "adding new documentation"
---

# Learned Documentation

This directory contains agent-discoverable documentation for AI assistants.

## Purpose

Learned docs provide structured guidance that AI agents can discover based on \
`read_when` conditions in frontmatter.

## Structure

Each markdown file requires YAML frontmatter:

- `title`: Document title (required)
- `read_when`: Conditions for when to read (required)
- `tripwires` (optional): Action-triggered rules

## Commands

- `erk docs sync` - Regenerate index files from frontmatter
- `erk docs validate` - Validate frontmatter

## Getting Started

1. Create markdown files with proper frontmatter
2. Organize related docs in subdirectories (categories)
3. Run `erk docs sync` to generate index files
"""

LEARNED_DOCS_INDEX = """\
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Run 'erk docs sync' to regenerate this file from document frontmatter. -->

# Agent Documentation

This index provides top-down navigation for agent-discoverable documentation.
Use the `read_when` conditions listed with each document to decide what to read
based on your current task. This enables progressive disclosure - read only what
you need, when you need it.

<!-- This index is automatically populated by 'erk docs sync'. -->

## Categories

<!-- Subdirectories will be listed here once created. -->

## Uncategorized

<!-- Top-level documents will be listed here. -->
<!-- Example: **[my-doc.md](my-doc.md)** — when to read condition 1, condition 2 -->
"""

LEARNED_DOCS_SKILL = """\
---
name: learned-docs
description: This skill should be used when writing, modifying, or reorganizing
  documentation in docs/learned/. Use when creating new documents, updating frontmatter,
  choosing categories, creating index files, updating routing tables, or moving
  files between categories. Essential for maintaining consistent documentation structure.
---

# Learned Documentation Guide

Overview: `docs/learned/` contains agent-focused documentation with:

- YAML frontmatter for routing and discovery
- Hierarchical category organization
- Index files for category navigation

## Document Registry

@docs/learned/index.md

## Frontmatter Requirements

Every markdown file (except index.md) MUST have:

```yaml
---
title: Document Title
read_when:
  - "first condition"
  - "second condition"
---
```

### Required Fields

| Field       | Type         | Purpose                                    |
| ----------- | ------------ | ------------------------------------------ |
| `title`     | string       | Human-readable title for index tables      |
| `read_when` | list[string] | Conditions when agent should read this doc |

### Writing Effective read_when Values

- Use gerund phrases: "creating a plan", "styling CLI output"
- Be specific: "fixing merge conflicts in tests" not "tests"
- Include 2-4 conditions covering primary use cases

## Document Structure Template

```markdown
---
title: [Clear Document Title]
read_when:
  - "[first condition]"
  - "[second condition]"
---

# [Title Matching Frontmatter]

[1-2 sentence overview]

## [Main Content Sections]

[Organized content with clear headers]
```

## Category Placement Guidelines

1. **Match by topic** - Does the doc clearly fit one category?
2. **Match by related docs** - Are similar docs already in a category?
3. **When unclear** - Place at root level; categorize later when patterns emerge
4. **Create new category** - When 3+ related docs exist at root level

## Validation

Run before committing:

```bash
erk docs sync      # Regenerate index files
erk docs validate  # Check frontmatter
```

## Quick Reference

- Category index: docs/learned/index.md
- Regenerate indexes: `erk docs sync`
"""


class LearnedDocsCapability(Capability):
    """Capability for the learned-docs agent documentation system."""

    @property
    def name(self) -> str:
        return "learned-docs"

    @property
    def description(self) -> str:
        return "Autolearning documentation system"

    @property
    def scope(self) -> CapabilityScope:
        return "project"

    @property
    def installation_check_description(self) -> str:
        return "docs/learned/ directory exists"

    @property
    def artifacts(self) -> list[CapabilityArtifact]:
        # Note: Category tripwires (e.g., architecture/tripwires.md) are auto-generated
        # by 'erk docs sync' from document frontmatter, not listed here as static artifacts
        return [
            CapabilityArtifact(path="docs/learned/", artifact_type="directory"),
            CapabilityArtifact(path="docs/learned/README.md", artifact_type="file"),
            CapabilityArtifact(path="docs/learned/index.md", artifact_type="file"),
            CapabilityArtifact(path=".claude/skills/learned-docs/", artifact_type="directory"),
            CapabilityArtifact(path=".claude/skills/learned-docs/SKILL.md", artifact_type="file"),
        ]

    @property
    def managed_artifacts(self) -> list[ManagedArtifact]:
        """Declare learned-docs skill as managed artifact."""
        return [ManagedArtifact(name="learned-docs", artifact_type="skill")]

    def is_installed(self, repo_root: Path | None) -> bool:
        """Check if docs/learned/ directory exists."""
        assert repo_root is not None, "LearnedDocsCapability requires repo_root"
        return (repo_root / "docs" / "learned").exists()

    def install(self, repo_root: Path | None) -> CapabilityResult:
        """Create docs/learned/ directory and learned-docs skill."""
        assert repo_root is not None, "LearnedDocsCapability requires repo_root"
        created_files: list[str] = []

        # Create docs/learned/ directory
        docs_dir = repo_root / "docs" / "learned"
        if not docs_dir.exists():
            docs_dir.mkdir(parents=True)
            created_files.append("docs/learned/")

            (docs_dir / "README.md").write_text(LEARNED_DOCS_README, encoding="utf-8")
            created_files.append("docs/learned/README.md")

            (docs_dir / "index.md").write_text(LEARNED_DOCS_INDEX, encoding="utf-8")
            created_files.append("docs/learned/index.md")
            # Note: Category tripwires (e.g., architecture/tripwires.md) are auto-generated
            # by 'erk docs sync' from document frontmatter

        # Create skill
        skill_dir = repo_root / ".claude" / "skills" / "learned-docs"
        if not skill_dir.exists():
            skill_dir.mkdir(parents=True)
            created_files.append(".claude/skills/learned-docs/")

        skill_file = skill_dir / "SKILL.md"
        if not skill_file.exists():
            skill_file.write_text(LEARNED_DOCS_SKILL, encoding="utf-8")
            created_files.append(".claude/skills/learned-docs/SKILL.md")

        if not created_files:
            return CapabilityResult(
                success=True,
                message="docs/learned/ already exists",
            )

        return CapabilityResult(
            success=True,
            message="Created docs/learned/",
            created_files=tuple(created_files),
        )

    def uninstall(self, repo_root: Path | None) -> CapabilityResult:
        """Remove docs/learned/ directory and learned-docs skill."""
        assert repo_root is not None, "LearnedDocsCapability requires repo_root"
        import shutil

        removed: list[str] = []

        # Remove skill directory
        skill_dir = repo_root / ".claude" / "skills" / "learned-docs"
        if skill_dir.exists():
            shutil.rmtree(skill_dir)
            removed.append(".claude/skills/learned-docs/")

        # Remove docs/learned directory
        docs_dir = repo_root / "docs" / "learned"
        if docs_dir.exists():
            shutil.rmtree(docs_dir)
            removed.append("docs/learned/")

        if not removed:
            return CapabilityResult(
                success=True,
                message="learned-docs not installed",
            )

        return CapabilityResult(
            success=True,
            message=f"Removed {', '.join(removed)}",
        )
