"""``mgf-fed feedback-howto`` — print the FEEDBACK.md submission flow.

Closes the v0.10.0 deliverable: every consumer (Claude or human)
should know how to file feedback against mgf-common — sharp edges,
roadmap requests, design questions — through the canonical
:file:`FEEDBACK.md` channel rather than ad-hoc emails or one-off
issues that get lost.

Two modes:

  - ``mgf-fed feedback-howto`` — print a how-to overview (severity
    guide, channel, the §1.4 entry template explained).
  - ``mgf-fed feedback-howto --template`` — print just the entry
    template, ready to paste into FEEDBACK.md §2.
  - ``mgf-fed feedback-howto --url`` — print the canonical URL of
    FEEDBACK.md on codeberg (for piping or browser-open).
"""

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import argparse


_FEEDBACK_URL = "https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md"


_OVERVIEW = """\
Submitting feedback to mgf-common
=================================

mgf-common's FEEDBACK.md is the canonical channel for sharp
edges, roadmap requests, and design questions. Every entry
follows a uniform shape so the document is machine-actionable
(both AI agents and human reviewers can grep it cleanly).

Where to file:
  {url}

Severity guide (pick one when you submit):
  🔴 Blocker        — Getting it wrong requires a breaking
                      change to fix later. MUST be decided
                      before v1.0.
  🟡 High           — Significant quality-of-life issue.
                      Painful to live with, additive to add
                      later.
  🟢 Nice-to-have   — Real value, not urgent.
  💭 Aspirational   — Long-term direction input. Not actionable
                      today.

How to submit:

  1. Fork mgf-common (or use your existing checkout).
  2. Add an entry to FEEDBACK.md §2 using the template
     (run `mgf-fed feedback-howto --template` to print it).
  3. Pick a fresh ID. The convention is `<AREA>-<NN>`:
       AREA  = capitalized domain prefix (e.g., HTTP, DB,
               API, CONFIG, SEC, TEST)
       NN    = 2-digit sequence within that area
     Examples: API-09, HTTP-03, DB-01.
  4. Open a PR against mgf-common.
  5. Triage happens in the PR thread. Decision lands in the
     entry's `Decision` field.
  6. When shipped, the entry moves to §4 with commit SHA +
     release tag + one-line retrospective.

Tips:

  - Submit OPEN entries even if you don't have a suggested
    fix — surfacing the concern is half the value.
  - Rejected entries stay in §5 (with rationale) so future
    consumers don't re-raise the same concern.
  - If your concern overlaps an existing OPEN entry, comment
    on the existing entry's PR rather than opening a duplicate.

For the entry template:
  mgf-fed feedback-howto --template
"""


_TEMPLATE = """\
### `<AREA>-<NN>` — One-line title

| Field | Value |
|---|---|
| Status | OPEN |
| Severity | 🔴 / 🟡 / 🟢 / 💭 |
| Submitter | <Project name> (commit `<sha>` if applicable) |
| Submitted | YYYY-MM-DD |
| Decision | pending |
| Decided on | — |
| Scheduled for | — |
| Shipped in | — |

**Concern.** What's wrong or missing. One paragraph.

**Why it matters.** Why this affects real consumers. One paragraph.
Cite specific call sites if you can.

**Suggested shape.** Concrete proposal — code snippet, prose, or
both. Not required to be the final answer; required to be a
starting point.

**Cost if deferred past v1.0.** The "why now" argument. (For
roadmap-shaped requests, "Cost if deferred" can be N/A.)

**Decision rationale.** *(Filled when triaged.)* Why accepted /
rejected / deferred / scheduled.

**Retrospective.** *(Filled when shipped.)* Did the suggested
shape survive contact with implementation? What changed and why?
"""


def add_feedback_args(parser: argparse.ArgumentParser) -> None:
    """Register the ``feedback`` subcommand's arguments."""
    parser.add_argument(
        "--template",
        action="store_true",
        help=(
            "Print just the FEEDBACK.md entry template, ready to "
            "paste into a fresh entry. Useful for scripted workflows."
        ),
    )
    parser.add_argument(
        "--url",
        action="store_true",
        help=(
            "Print the canonical FEEDBACK.md URL on codeberg. "
            "Useful for piping into a browser-open command."
        ),
    )


def run_feedback(args: argparse.Namespace) -> int:
    """Print the requested feedback resource."""
    if args.url:
        print(_FEEDBACK_URL)
        return 0
    if args.template:
        print(_TEMPLATE)
        return 0
    print(_OVERVIEW.format(url=_FEEDBACK_URL))
    return 0


__all__ = ["add_feedback_args", "run_feedback"]
