"""Target definitions for Claude Code plugins."""

from __future__ import annotations

from pants.engine.target import (
    COMMON_TARGET_FIELDS,
    BoolField,
    StringField,
    StringSequenceField,
    Target,
)
from pants.util.strutil import softwrap


class PluginNameField(StringField):
    """The name of the Claude Code plugin to install."""

    alias = "plugin"
    required = True
    help = softwrap(
        """
        The name of the Claude Code plugin to install.

        This should be the plugin identifier, e.g., "commit-commands" or "github".
        """
    )


class MarketplaceField(StringField):
    """The marketplace to install the plugin from."""

    alias = "marketplace"
    required = True
    help = softwrap(
        """
        The marketplace identifier to install the plugin from.

        Examples:
        - "claude-plugins-official" (official Anthropic marketplace)
        - "anthropics-claude-code" (demo plugins marketplace)
        - "your-org-name" (custom marketplace you've added)

        The marketplace must be added first using:
            /plugin marketplace add owner/repo
        """
    )


class ScopeField(StringField):
    """Installation scope for this plugin."""

    alias = "scope"
    default = None  # Use subsystem default
    help = softwrap(
        """
        The installation scope for this plugin.

        Valid values are:
        - "project": Install for all collaborators on the repository
        - "user": Install for the current user across all projects
        - "local": Install for yourself in this repository only

        If not specified, uses the default_scope from [claude-plugins] options.
        """
    )


class EnabledField(BoolField):
    """Whether this plugin should be installed."""

    alias = "enabled"
    default = True
    help = softwrap(
        """
        Whether this plugin should be installed.

        Set to False to temporarily disable installation without removing the target.
        """
    )


class DescriptionField(StringField):
    """Human-readable description of why this plugin is used."""

    alias = "description"
    default = None
    help = softwrap(
        """
        Optional description explaining why this plugin is included.

        This is for documentation purposes only and does not affect installation.
        """
    )


class TagsField(StringSequenceField):
    """Tags for organizing and filtering plugins."""

    alias = "tags"
    help = softwrap(
        """
        Tags for organizing and filtering plugins.

        You can use tags to install subsets of plugins, e.g.:
            pants claude-install --tag=lsp
            pants claude-install --tag=required
        """
    )


class ClaudePlugin(Target):
    """A Claude Code plugin to be installed in this project.

    Define these targets in your BUILD files to declare which Claude Code plugins
    should be installed when running `pants claude-install`.

    Example:

        # BUILD file
        claude_plugin(
            name="github-integration",
            plugin="github",
            marketplace="claude-plugins-official",
            scope="project",
            description="GitHub integration for PR workflows",
        )

        claude_plugin(
            name="commit-commands",
            plugin="commit-commands",
            marketplace="anthropics-claude-code",
            scope="project",
            tags=["workflow"],
        )

    Then install all plugins with:

        pants claude-install ::

    Or install specific plugins:

        pants claude-install path/to:github-integration
    """

    alias = "claude_plugin"
    core_fields = (
        *COMMON_TARGET_FIELDS,
        PluginNameField,
        MarketplaceField,
        ScopeField,
        EnabledField,
        DescriptionField,
        TagsField,
    )
    help = softwrap(
        """
        A Claude Code plugin to install in this project.

        Use the `claude-install` goal to install all defined plugins:

            pants claude-install ::
        """
    )
