#!/usr/bin/env python3
"""为执行域 doc_id 生成最小闭环骨架：docs + ansible/files + verify playbook。

符合 Epic 1 Story 1.3：默认通过 verify_common noop 任务链接入集群基线断言。
"""
from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent.parent
DOCS_DIR = ROOT / "docs"
FILES_BASE = ROOT / "ansible" / "files"
VERIFY_DIR = ROOT / "ansible" / "playbooks" / "verify"

EXEC_ID_RE = re.compile(r"^(0[1-9]|[1-9][0-9])-(0[1-9]|[1-9][0-9])$")


def doc_markdown(doc_id: str, slug: str, title: str) -> str:
    return f"""# {title}

> **doc_id**：`{doc_id}` · 执行域文档（参与 `verify.sh list/full`）。

## 契约与真源

- **清单真源目录**：`ansible/files/{doc_id}/`（不要在本文重复粘贴大块 YAML 作为第二真源）。
- **Ansible 验证入口**：`ansible/playbooks/verify/{doc_id}.yml`
- 基线断言复用 `ansible/roles/verify_common/tasks/noop-doc-verify.yml`（集群连通 + 可选 manifest dry-run）。

验收命令：

```bash
./ansible/bin/verify.sh run {doc_id}
```

## 正文

（编写步骤说明；引用清单时请写相对于仓库的路径，例如 `ansible/files/{doc_id}/demo.yaml`。）
"""


def files_readme(doc_id: str) -> str:
    return f"""# {doc_id} 清单真源

将本篇相关的 Kubernetes YAML、Helm values 等放在此目录。

- 命名建议：小写 + 连字符，例如 `app-deploy.yaml`。
- 示例或非集群清单可使用 `*.example.yaml` 后缀；noop 验证会跳过这类文件的 `kubectl dry-run`。
"""


def verify_playbook(doc_id: str, doc_filename: str) -> str:
    return f"""---
- name: "{doc_id} noop verify (scaffold)"
  hosts: localhost
  gather_facts: false
  vars:
    repo_root: "{{{{ playbook_dir }}}}/../../.."
    doc_id: "{doc_id}"
    doc_filename: "{doc_filename}"
  tasks:
    - name: Include noop doc verify role tasks
      ansible.builtin.include_role:
        name: verify_common
        tasks_from: noop-doc-verify.yml
"""


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser(
        description="生成执行域 doc_id 最小骨架：docs、ansible/files/<doc_id>/、verify playbook。"
    )
    p.add_argument("doc_id", help="如 04-15（XX-YY，XX>0 且 YY>0）")
    p.add_argument("slug", help="文档文件名段，如 k3s-traefik-acme（生成 docs/<doc_id>-<slug>.md）")
    p.add_argument("--title", default="", help="文档 H1 标题（默认从 slug 生成）")
    p.add_argument("--dry-run", action="store_true", help="只打印将创建的路径，不写盘")
    p.add_argument("--force", action="store_true", help="覆盖已存在的同名目标文件")
    return p.parse_args()


def validate_slug(slug: str) -> None:
    if not slug or len(slug) > 200:
        print("ERR: slug 长度须在 1～200 之间", file=sys.stderr)
        sys.exit(2)
    if slug.strip() != slug:
        print("ERR: slug 首尾不应含空白", file=sys.stderr)
        sys.exit(2)
    if "/" in slug or "\\" in slug or slug.startswith("."):
        print("ERR: slug 不允许路径分隔符或以 '.' 开头", file=sys.stderr)
        sys.exit(2)


def main() -> None:
    args = parse_args()
    doc_id = args.doc_id.strip()
    slug = args.slug.strip()
    if not EXEC_ID_RE.fullmatch(doc_id):
        print(f"ERR: doc_id 非法（须匹配执行域 XX-YY）：{doc_id!r}", file=sys.stderr)
        sys.exit(2)
    validate_slug(slug)

    doc_filename = f"{doc_id}-{slug}.md"
    title = args.title.strip() or slug.replace("-", " ").replace("_", " ")

    target_doc = DOCS_DIR / doc_filename
    target_pb = VERIFY_DIR / f"{doc_id}.yml"
    files_dir = FILES_BASE / doc_id
    target_readme = files_dir / "README.md"

    # 同一 doc_id 仅允许一篇 docs/<doc_id>-*.md（与 validate_matrix 一致）
    siblings = sorted(DOCS_DIR.glob(f"{doc_id}-*.md"))
    for p in siblings:
        if p.name != doc_filename:
            print(
                f"ERR: doc_id={doc_id} 已存在其他文档 {p.relative_to(ROOT)}，"
                f"请先删除或合并，不能新增第二篇。",
                file=sys.stderr,
              )
            sys.exit(2)

    planned = [
        ("docs", target_doc, doc_markdown(doc_id, slug, title)),
        ("files README", target_readme, files_readme(doc_id)),
        ("verify playbook", target_pb, verify_playbook(doc_id, doc_filename)),
    ]

    for label, path, content in planned:
        if path.exists() and not args.force:
            print(f"ERR: 已存在（使用 --force 覆盖）：{path.relative_to(ROOT)}", file=sys.stderr)
            sys.exit(2)

    if args.dry_run:
        print("[dry-run] 将创建：")
        for label, path, _ in planned:
            print(f"  - {label}: {path.relative_to(ROOT)}")
        return

    for label, path, content in planned:
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(content, encoding="utf-8")
        print(f"[OK] wrote {path.relative_to(ROOT)}")

    print("")
    print("下一步：编辑正文与清单，然后执行：")
    print(f"  ./scripts/offline-check.sh")
    print(f"  ./ansible/bin/verify.sh run {doc_id}")


if __name__ == "__main__":
    main()