# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..spec import Action
from ._shared import ATTACHMENTS, body, confirm, path, query


ISSUE_ACTIONS: tuple[Action, ...] = (
    Action(
        name="list_issues",
        method="GET",
        path="/issues",
        summary="List issue tickets from the Gitea tracker",
        requires_auth=False,
        params=(
            query("state", "Filter by state: open, closed, or all."),
            query("page", "1-based page number."),
        ),
    ),
    Action(
        name="create_issue",
        method="POST",
        path="/issues/create",
        summary="Report an issue. It is rewritten by AI and filed on the tracker.",
        description=(
            "Queues a background issue creation job and returns {uid, status_url}. Poll the "
            "status_url with issue_job_status until status is 'done', then show the user the "
            "issue_url pointing at the filed ticket."
        ),
        params=(
            body("title", "Issue title.", required=True),
            body("description", "Issue description.", required=True),
        ),
    ),
    Action(
        name="planning_report_generate",
        method="POST",
        path="/issues/planning",
        summary="Queue an admin planning report of open tickets.",
        description=(
            "Queues a background job that builds a phased, ordered markdown implementation "
            "document for open tickets and returns {uid, status_url}. Pass 'numbers' as a "
            "comma-separated list of issue numbers to plan only those tickets; omit it to plan "
            "every open ticket. Each ticket's full description is reproduced verbatim, both "
            "inline and in a 'Source Tickets (verbatim)' appendix, so the document is "
            "self-contained. Poll with planning_status until status is 'done', then show the "
            "user the markdown and the download_url (fetch the file itself with "
            "planning_download if asked). Admin only."
        ),
        params=(
            body(
                "numbers",
                "Comma-separated issue numbers to include (e.g. '1,4,7'). Omit for all open tickets.",
            ),
        ),
        requires_auth=True,
        requires_admin=True,
    ),
    Action(
        name="planning_status",
        method="GET",
        path="/issues/planning/{uid}",
        summary="Check a planning report job and read it once finished",
        description=(
            "Returns the job status. When status is 'done', the full markdown document and "
            "download_url are populated; while 'pending' or 'running', poll again shortly. Admin only."
        ),
        params=(path("uid", "Planning job uid returned by planning_report_generate."),),
        requires_auth=True,
        requires_admin=True,
    ),
    Action(
        name="planning_download",
        method="GET",
        path="/issues/planning/{uid}/download",
        summary="Download the finished planning report file",
        description=(
            "Returns the raw markdown file of a finished planning report. Use planning_status "
            "first; this is only needed if the user wants the file content fetched directly "
            "rather than shown inline. Admin only."
        ),
        params=(path("uid", "Planning job uid returned by planning_report_generate."),),
        requires_auth=True,
        requires_admin=True,
    ),
    Action(
        name="issue_job_status",
        method="GET",
        path="/issues/jobs/{uid}",
        summary="Poll an issue creation job and obtain the filed issue ticket URL once finished",
        description=(
            "Returns the job status. When status is 'done', issue_url and number are populated; "
            "while 'pending' or 'running', poll again shortly."
        ),
        params=(path("uid", "Issue job uid returned by create_issue."),),
        requires_auth=False,
    ),
    Action(
        name="view_issue",
        method="GET",
        path="/issues/{number}",
        summary="View an issue ticket and its developer updates",
        requires_auth=False,
        params=(path("number", "The issue ticket number from a /issues listing."),),
    ),
    Action(
        name="comment_issue",
        method="POST",
        path="/issues/{number}/comment",
        summary="Post a comment on an issue ticket, attributed to the current user",
        params=(
            path("number", "The issue ticket number."),
            body("body", "Comment text.", required=True),
        ),
    ),
    Action(
        name="set_issue_status",
        method="POST",
        path="/issues/{number}/status",
        summary="Change an issue ticket status (admin only)",
        requires_admin=True,
        params=(
            path("number", "The issue ticket number."),
            body("status", "New status: open or closed.", required=True),
        ),
    ),
    Action(
        name="list_issue_attachments",
        method="GET",
        path="/issues/{number}/attachments",
        summary="List the files attached to an issue ticket",
        requires_auth=False,
        params=(path("number", "The issue ticket number."),),
    ),
    Action(
        name="add_issue_attachment",
        method="POST",
        path="/issues/{number}/attachments",
        summary="Attach already-uploaded files to an open issue ticket",
        description=(
            "Upload files first with upload_file, then pass their uids here. Only works while "
            "the issue is open; the files are mirrored to the tracker."
        ),
        params=(
            path("number", "The issue ticket number."),
            body("attachment_uids", ATTACHMENTS, required=True),
        ),
    ),
    Action(
        name="delete_issue_attachment",
        method="DELETE",
        path="/issues/{number}/attachments/{uid}",
        summary="Delete a file from an open issue ticket (your own, or any when administrator). Soft delete, confirmation required",
        params=(
            path("number", "The issue ticket number."),
            path("uid", "The attachment uid."),
            confirm(),
        ),
    ),
    Action(
        name="add_comment_attachment",
        method="POST",
        path="/issues/{number}/comments/{cid}/attachments",
        summary="Attach already-uploaded files to an issue comment (issue must be open)",
        params=(
            path("number", "The issue ticket number."),
            path("cid", "The Gitea comment id."),
            body("attachment_uids", ATTACHMENTS, required=True),
        ),
    ),
    Action(
        name="delete_comment_attachment",
        method="DELETE",
        path="/issues/{number}/comments/{cid}/attachments/{uid}",
        summary="Delete a file from an issue comment (your own, or any when administrator). Soft delete, confirmation required",
        params=(
            path("number", "The issue ticket number."),
            path("cid", "The Gitea comment id."),
            path("uid", "The attachment uid."),
            confirm(),
        ),
    ),
)
