import angreal

@angreal.command(
    name="deploy",
    about="Deploy to environment",
    tool=angreal.ToolDescription(
        """
        Deploy the application to a specified environment.

        ## When to use
        - After successful build and tests pass
        - When user explicitly requests deployment

        ## When NOT to use
        - Directly from feature branches
        - Without running tests first

        ## Examples
        ```
        angreal deploy --env staging
        angreal deploy --env production --version v1.2.3
        ```
        """,
        risk_level="destructive"
    )
)
def deploy(env, version=None):
    pass

angreal.ToolDescription(
    description,          # Prose description (required)
    risk_level="safe"     # "safe", "read_only", or "destructive"
)

tool=angreal.ToolDescription(
    """
    One-line summary of what the tool does.

    ## When to use
    - Scenario 1
    - Scenario 2

    ## When NOT to use
    - Anti-pattern 1
    - Anti-pattern 2

    ## Examples
    Concrete invocation examples with real arguments

    ## Preconditions
    What must be true before running

    ## Output
    What to expect from the tool
    """,
    risk_level="safe"
)

tool=angreal.ToolDescription("Runs tests")

tool=angreal.ToolDescription(
    """
    Run the complete test suite including unit and integration tests.

    ## When to use
    - Before committing changes
    - After pulling changes to verify environment
    - As part of CI/CD validation

    ## Output
    Returns exit code 0 if all tests pass, non-zero otherwise.
    """
)

tool=angreal.ToolDescription(
    """
    Build documentation from source.

    ## Examples
    ```
    # Build to default output
    angreal docs build

    # Build with specific output path
    angreal docs build --output ./site

    # Build in watch mode
    angreal docs build --watch
    ```
    """
)

tool=angreal.ToolDescription(
    """
    Install project dependencies.

    ## Common Failures
    - **Network error**: Check internet connectivity
    - **Permission denied**: May need sudo or virtual environment
    - **Version conflict**: Check requirements.txt

    ## Recovery
    If installation fails:
    1. Clear cache: `angreal dev clean-cache`
    2. Retry installation
    """
)

tool=angreal.ToolDescription(
    """
    Run unit tests only (fast).

    ## Related Tasks
    - `test.integration` - Integration tests (slower)
    - `test.all` - Complete test suite
    - `lint.check` - Check style (run before tests)

    ## Typical Workflow
    1. `angreal lint check`
    2. `angreal test unit` - Fast feedback
    3. `angreal test all` - Full validation
    """
)

tool=angreal.ToolDescription(
    """
    Build the project for release distribution.

    ## When to use
    - Creating a release build
    - Before running deployment tasks

    ## Preconditions
    - Dependencies installed (`angreal dev check-deps`)
    - Source compiles without errors

    ## Output
    - Artifacts written to `dist/`
    - Returns 0 on success
    """,
    risk_level="safe"
)

tool=angreal.ToolDescription(
    """
    Apply pending database migrations.

    ## When to use
    - After pulling changes with new migrations
    - During deployment to update schema

    ## When NOT to use
    - On production without backup
    - Without reviewing migration contents

    ## Recovery
    If migration fails:
    1. Check migration logs
    2. Run `angreal db rollback`
    3. Fix and retry
    """,
    risk_level="destructive"
)

tool=angreal.ToolDescription(
    """
    Check project status and health.

    ## When to use
    - Starting work to understand state
    - Debugging to gather context
    - Verifying environment setup

    ## Output
    Reports on git branch, dependencies, build state, test summary.
    """,
    risk_level="read_only"
)