"""cycle_advancer dry-run CLI entry.

task-2488 Phase B PoC. fixture에서 evidence를 로드하여
:class:`CycleAdvancer`를 호출하고 draft md만 생성한다. 실제
``.done`` / ``.escalate`` / ``.fail`` 파일이나 dispatch 호출은 절대 수행하지
않는다.

Usage::

    python3 tools/poc/cycle_advancer_dry_run.py \\
        --task-id task-2485 \\
        --fixture-dir tools/poc/cycle_advancer/fixtures \\
        --output-dir memory/poc/cycle_advancer \\
        --fixed-timestamp 2026-05-08T00:00:00Z

Determinism:
    timestamp 우선순위는 ``--fixed-timestamp`` > ``CYCLE_ADVANCER_FIXED_TS``
    환경변수 > 현재 UTC. 테스트는 ``--fixed-timestamp``를 지정한다.
"""

from __future__ import annotations

import argparse
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

# 패키지 import를 위해 workspace root를 sys.path 앞에 추가.
_WORKSPACE_ROOT = Path(__file__).resolve().parents[2]
if str(_WORKSPACE_ROOT) not in sys.path:
    sys.path.insert(0, str(_WORKSPACE_ROOT))

from tools.poc.cycle_advancer import CycleAdvancer, load_fixture  # noqa: E402
from tools.poc.cycle_advancer.output_writer import write_draft  # noqa: E402


_FIXED_TS_ENV = "CYCLE_ADVANCER_FIXED_TS"


def _resolve_timestamp(cli_value: str | None) -> str:
    """timestamp 결정 규칙을 한 곳에서 관리한다.

    우선순위:
        1. ``--fixed-timestamp`` CLI 값.
        2. ``CYCLE_ADVANCER_FIXED_TS`` 환경변수.
        3. 현재 UTC (마이크로초 제외, ``Z`` 접미사).

    Returns:
        ISO8601 + ``Z`` 형식의 timestamp 문자열.
    """
    if cli_value:
        return cli_value
    env_value = os.environ.get(_FIXED_TS_ENV)
    if env_value:
        return env_value
    now = datetime.now(timezone.utc).replace(microsecond=0)
    return now.strftime("%Y-%m-%dT%H:%M:%SZ")


def build_arg_parser() -> argparse.ArgumentParser:
    """CLI 인자 파서를 생성한다."""
    parser = argparse.ArgumentParser(
        prog="cycle_advancer_dry_run",
        description=(
            "cycle_advancer PoC dry-run. fixture evidence를 입력으로 받아 "
            "draft md만 생성합니다 (실제 dispatch / .done 생성 금지)."
        ),
    )
    parser.add_argument(
        "--task-id",
        required=True,
        help="source task_id (예: task-2485). fixture/{task-id}.json을 로드합니다.",
    )
    parser.add_argument(
        "--fixture-dir",
        required=True,
        type=Path,
        help="fixture 디렉토리. 격리된 사본만 두며 실제 memory/events 미사용.",
    )
    parser.add_argument(
        "--output-dir",
        required=True,
        type=Path,
        help="draft md 출력 디렉토리 (없으면 생성).",
    )
    parser.add_argument(
        "--fixed-timestamp",
        default=None,
        help=(
            "deterministic timestamp (ISO8601 + Z). 미지정 시 "
            f"{_FIXED_TS_ENV} 환경변수 또는 현재 UTC."
        ),
    )
    return parser


def main(argv: list[str] | None = None) -> int:
    """CLI entry point.

    Args:
        argv: 테스트용 argument list (``None``이면 ``sys.argv[1:]``).

    Returns:
        프로세스 종료 코드.
    """
    parser = build_arg_parser()
    args = parser.parse_args(argv)

    fixture_dir: Path = args.fixture_dir.resolve()
    output_dir: Path = args.output_dir.resolve()
    generated_at = _resolve_timestamp(args.fixed_timestamp)

    evidence = load_fixture(fixture_dir, args.task_id)
    advancer = CycleAdvancer()
    analysis = advancer.analyze(evidence)
    payload = advancer.build_draft_payload(
        evidence=evidence,
        analysis=analysis,
        generated_at=generated_at,
    )
    written_path = write_draft(payload, output_dir)

    print(f"[cycle_advancer/v1-mock] draft written: {written_path}")
    print(
        "  source_task_id={src} -> proposed_task_id={dst} "
        "(classification={cls}, chairman_required={cr})".format(
            src=payload.source_task_id,
            dst=payload.proposed_task_id,
            cls=payload.classification,
            cr=payload.chairman_required,
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())