"""Skill topic: users — complete parameter specs for one-shot agent execution."""

from turumba_cli.skills.registry import ParamSpec, SkillTopic, register_topics

topic = SkillTopic(
    name="users",
    summary="Manage users (team members within accounts, with role assignment)",
    commands=[
        "turumba users list",
        "turumba users get <user-id>",
        "turumba users create",
        "turumba users update <user-id>",
        "turumba users delete <user-id>",
    ],
    create_params=[
        ParamSpec(
            name="--email / -e",
            type="string (email)",
            required=True,
            description="User email address (max 255 chars). Must be unique.",
        ),
        ParamSpec(
            name="--given-name",
            type="string",
            required=True,
            description="Given (first) name (1-50 chars)",
        ),
        ParamSpec(
            name="--family-name",
            type="string",
            required=True,
            description="Family (last) name (1-50 chars)",
        ),
        ParamSpec(
            name="--account-id / -a",
            type="UUID",
            required=True,
            description="Account ID. Falls back to config default_account_id",
        ),
        ParamSpec(
            name="--role-id / -r",
            type="UUID",
            required=True,
            description="Role ID to assign the user within the account",
        ),
        ParamSpec(
            name="--phone",
            type="string",
            required=False,
            description="Phone number (max 20 chars)",
        ),
    ],
    notes=[
        "account_id is REQUIRED by the API. Use --account-id or set default: "
        "turumba config set default_account_id <uuid>",
        "role_id is REQUIRED — look up available roles first: "
        "turumba users list -f account_id:eq:<uuid> to see existing role assignments.",
        "email must be unique across the platform.",
        "Creating a user provisions a Cognito account and sends an invitation email.",
        "Update only supports: given_name, family_name, phone, role_id. "
        "Email cannot be changed after creation.",
        "Filterable fields: id, account_id, email, phone, given_name, family_name, "
        "created_at, updated_at.",
        "Sortable fields: email, full_name, created_at, updated_at.",
    ],
    examples=[
        # Create with all required fields
        "turumba users create --email user@example.com --given-name Abebe "
        "--family-name Kebede --role-id <role-uuid> --account-id <account-uuid>",
        # Create with default account_id and phone
        "turumba users create --email user@example.com --given-name Abebe "
        '--family-name Kebede --role-id <role-uuid> --phone "+251911123456"',
        # List users in an account
        "turumba users list -f account_id:eq:<account-uuid> -o json",
        # Filter by email
        "turumba users list -f email:contains:@example.com",
        # Filter by name
        "turumba users list -f given_name:icontains:abebe",
        # Get user details
        "turumba users get <user-id> -o json",
        # Update name
        "turumba users update <user-id> --given-name NewName --family-name NewFamily",
        # Update role
        "turumba users update <user-id> --role-id <new-role-uuid>",
    ],
    workflows=[
        {
            "name": "Onboard a new team member",
            "steps": [
                "turumba config set default_account_id <your-account-id>  # one-time setup",
                "turumba users list -o json  # see existing users and roles",
                "turumba users create --email new@example.com --given-name Abebe "
                "--family-name Kebede --role-id <role-uuid> -o json",
            ],
        },
        {
            "name": "Change a user's role",
            "steps": [
                "turumba users list -f email:eq:user@example.com -o json  # find user ID",
                "turumba users update <user-id> --role-id <new-role-uuid> -o json",
            ],
        },
    ],
    related=["auth", "overview"],
)

register_topics(topic)
