Embed Ai Tool

{
  "permissions": {
    "allow": [
      "Bash(python *)",
      "Bash(git *)",
      "Bash(cd *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(head *)",
      "Bash(mkdir *)",
      "Bash(echo *)"
    ]
  }
}

__pycache__/
.pytest_cache/
*.pyc
*.pyo
.DS_Store
Thumbs.db
.em_skill.json
.em_skill_meta.json

#!/usr/bin/env python3
"""em_skill 工具路径配置管理 CLI。

子命令:
  set <tool> <path> [--global]  保存工具路径
  get <tool>                    查询工具路径
  list                          列出所有已配置的工具
  remove <tool> [--global]      删除配置项
  path                          显示配置文件路径
"""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

_REPO_ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(_REPO_ROOT / "shared"))

from tool_config import (
    get_tool_path,
    list_tools,
    remove_tool_path,
    set_tool_path,
    user_config_path,
    workspace_config_path,
)


def cmd_set(args: argparse.Namespace) -> int:
    tool_path = str(Path(args.path).resolve())
    cfg_path = set_tool_path(args.tool, tool_path, global_=args.global_flag)
    level = "全局" if args.global_flag else "工作区"
    print(f"✅ 已保存 {args.tool} = {tool_path} ({level}: {cfg_path})")
    return 0


def cmd_get(args: argparse.Namespace) -> int:
    path = get_tool_path(args.tool)
    if path:
        print(path)
        return 0
    print(f"❌ 未找到 {args.tool} 的配置")
    return 1


def cmd_list(_args: argparse.Namespace) -> int:
    tools = list_tools()
    if not tools:
        print("ℹ️ 暂无已配置的工具")
        return 0
    print("📋 已配置的工具：")
    for name, info in sorted(tools.items()):
        print(f"  {name} = {info['path']}  [{info['source']}]")
    return 0


def cmd_remove(args: argparse.Namespace) -> int:
    removed = remove_tool_path(args.tool, global_=args.global_flag)
    if removed:
        level = "全局" if args.global_flag else "工作区"
        print(f"✅ 已删除 {args.tool} ({level})")
        return 0
    print(f"❌ 未找到 {args.tool} 的配置")
    return 1


def cmd_path(_args: argparse.Namespace) -> int:
    print(f"全局配置: {user_config_path()}")
    print(f"工作区配置: {workspace_config_path()}")
    return 0


def main() -> int:
    parser = argparse.ArgumentParser(
        description="em_skill 工具路径配置管理",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
示例:
  %(prog)s set openocd /usr/bin/openocd
  %(prog)s set uv4 "C:\\Keil_v5\\UV4\\UV4.exe" --global
  %(prog)s get openocd
  %(prog)s list
  %(prog)s remove openocd
  %(prog)s path
        """,
    )
    sub = parser.add_subparsers(dest="command")

    # set
    p_set = sub.add_parser("set", help="保存工具路径")
    p_set.add_argument("tool", help="工具名称")
    p_set.add_argument("path", help="工具路径")
    p_set.add_argument("--global", dest="global_flag", action="store_true", help="保存到全局配置")

    # get
    p_get = sub.add_parser("get", help="查询工具路径")
    p_get.add_argument("tool", help="工具名称")

    # list
    sub.add_parser("list", help="列出所有已配置的工具")

    # remove
    p_rm = sub.add_parser("remove", help="删除配置项")
    p_rm.add_argument("tool", help="工具名称")
    p_rm.add_argument("--global", dest="global_flag", action="store_true", help="从全局配置删除")

    # path
    sub.add_parser("path", help="显示配置文件路径")

    args = parser.parse_args()
    if not args.command:
        parser.print_help()
        return 1

    dispatch = {
        "set": cmd_set,
        "get": cmd_get,
        "list": cmd_list,
        "remove": cmd_remove,
        "path": cmd_path,
    }
    return dispatch[args.command](args)


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
"""embed-ai-tool 安装脚本 — 零依赖，仅标准库。

用法：
    python3 scripts/install.py /path/to/project              # 默认：分析工程，输出推荐集（不安装）
    python3 scripts/install.py /path/to/project --skills build-cmake flash-openocd
    python3 scripts/install.py /path/to/project --yes         # 确认全量安装
    python3 scripts/install.py /path/to/project --force       # 强制覆盖
    python3 scripts/install.py /path/to/project --detect      # 安装后探测工具路径
    python3 scripts/install.py /path/to/project --uninstall   # 卸载
    python3 scripts/install.py /path/to/project --status      # 查看安装状态
    python3 scripts/install.py /path/to/project --analyze     # 显式只分析不安装
    python3 scripts/install.py --list                         # 列出可用 skill
"""

from __future__ import annotations

import argparse
import json
import re
import shutil
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path

# Windows 中文控制台默认 GBK 编码，强制 stdout/stderr 用 UTF-8 避免 emoji 崩溃
if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
    try:
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
    except (AttributeError, OSError):
        pass

REPO_ROOT = Path(__file__).resolve().parent.parent
SKILLS_SRC = REPO_ROOT / "skills"
SHARED_SRC = REPO_ROOT / "shared"
META_FILENAME = ".em_skill_meta.json"

SKIP_PATTERNS = {"__pycache__", ".pyc", ".pyo", ".DS_Store", "Thumbs.db"}

DETECT_TOOLS = [
    "cmake",
    "ninja",
    "make",
    "openocd",
    "arm-none-eabi-gcc",
    "arm-none-eabi-gdb",
    "gdb-multiarch",
    "platformio",
    "pio",
    "idf.py",
    "JLinkExe",
    "JLinkGDBServerCLExe",
    "cppcheck",
    "clang-tidy",
]


def _should_skip(path: Path) -> bool:
    for part in path.parts:
        if part in SKIP_PATTERNS or part.endswith((".pyc", ".pyo")):
            return True
    return False


def _git_short_hash() -> str:
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--short", "HEAD"],
            cwd=REPO_ROOT,
            capture_output=True,
            text=True,
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except FileNotFoundError:
        pass
    return "unknown"


def _copy_tree(src: Path, dst: Path, force: bool = False) -> tuple[int, int]:
    """递归拷贝目录，返回 (copied, skipped) 计数。"""
    copied = 0
    skipped = 0
    for item in sorted(src.rglob("*")):
        if not item.is_file():
            continue
        rel = item.relative_to(src)
        if _should_skip(rel):
            continue
        target = dst / rel
        if target.exists() and not force:
            skipped += 1
            continue
        target.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(item, target)
        copied += 1
    return copied, skipped


def _available_skills() -> list[str]:
    if not SKILLS_SRC.is_dir():
        return []
    return sorted(
        d.name
        for d in SKILLS_SRC.iterdir()
        if d.is_dir() and (d / "SKILL.md").exists()
    )


def _read_skill_description(skill_name: str) -> str:
    skill_md = SKILLS_SRC / skill_name / "SKILL.md"
    if not skill_md.is_file():
        return ""
    text = skill_md.read_text(encoding="utf-8")
    m = re.search(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
    if not m:
        return ""
    for line in m.group(1).splitlines():
        line = line.strip()
        if line.startswith("description:"):
            desc = line[len("description:"):].strip()
            return desc.strip("\"'")
    return ""


def _skills_dir(project: Path) -> Path:
    return project / ".claude" / "skills"


def _meta_path(project: Path) -> Path:
    return _skills_dir(project) / META_FILENAME


def _load_meta(project: Path) -> dict:
    mp = _meta_path(project)
    if mp.is_file():
        try:
            return json.loads(mp.read_text(encoding="utf-8"))
        except (json.JSONDecodeError, OSError):
            pass
    return {}


def _save_meta(project: Path, meta: dict) -> None:
    mp = _meta_path(project)
    mp.parent.mkdir(parents=True, exist_ok=True)
    mp.write_text(
        json.dumps(meta, indent=2, ensure_ascii=False) + "\n",
        encoding="utf-8",
    )


# ── Commands ─────────────────────────────────────────────────────────


# 工程分析规则：文件特征 → (标签, 关联 skill 列表)
# 顺序即优先级，构建系统一旦命中就不再检查低优先级规则
ANALYZE_RULES_BUILD = [
    (("*.uvprojx", "*.uvproj"), "Keil MDK", ["build-keil", "flash-keil"]),
    (("*.ewp", "*.eww"), "IAR EWARM", ["build-iar"]),
    (("platformio.ini",), "PlatformIO", ["build-platformio", "flash-platformio", "debug-platformio"]),
    (("sdkconfig",), "ESP-IDF", ["build-idf", "flash-idf"]),
    (("CMakeLists.txt",), "CMake", ["build-cmake"]),
    (("Makefile", "makefile", "GNUmakefile"), "Makefile", ["build-makefile"]),
]

ANALYZE_TOOLS_CHAIN = [
    ("arm-none-eabi-gcc", "ARM Cortex-M"),
    ("xtensa-esp32-elf-gcc", "ESP32 (Xtensa)"),
    ("riscv64-unknown-elf-gcc", "RISC-V"),
]

ANALYZE_DEBUGGERS = [
    ("JLinkExe", "J-Link", ["flash-jlink", "debug-jlink"]),
]


def _glob_any(project: Path, patterns: tuple[str, ...]) -> bool:
    for pat in patterns:
        if any(project.glob(pat)):
            return True
    return False


def cmd_analyze(project: Path) -> None:
    """分析工程类型，输出推荐安装的 skill 集，不执行任何写入。"""
    print(f"工程分析：{project}\n")

    detected: list[tuple[str, str, list[str]]] = []

    # 构建系统（命中即停，避免混合工程误判）
    build_hit = False
    for patterns, label, skills in ANALYZE_RULES_BUILD:
        # ESP-IDF 需要额外检查 components/
        if label == "ESP-IDF" and not (project / "components").is_dir():
            continue
        # Makefile 仅在没有 CMakeLists.txt 时才算
        if label == "Makefile" and (project / "CMakeLists.txt").is_file():
            continue
        if _glob_any(project, patterns):
            detected.append(("构建系统", label, skills))
            build_hit = True
            break

    # 调试器
    launch_json = project / ".vscode" / "launch.json"
    if launch_json.is_file():
        try:
            text = launch_json.read_text(encoding="utf-8", errors="ignore")
            if "openocd" in text.lower():
                detected.append(("调试器", "OpenOCD（launch.json）", ["flash-openocd", "debug-gdb-openocd"]))
        except OSError:
            pass
    if (project / "openocd.cfg").is_file() or (project / "openocd.cfg.in").is_file():
        detected.append(("调试器", "OpenOCD 配置存在", ["flash-openocd", "debug-gdb-openocd"]))
    if _glob_any(project, ("*.jlink",)):
        detected.append(("调试器", "J-Link（.jlink 文件）", ["flash-jlink", "debug-jlink"]))
    else:
        for tool, label in [("JLinkExe", "J-Link")]:
            if shutil.which(tool):
                detected.append(("调试器", f"{label}（PATH 可用）", ["flash-jlink", "debug-jlink"]))
                break

    # 工具链
    for tool, label in ANALYZE_TOOLS_CHAIN:
        if shutil.which(tool):
            detected.append(("工具链", label, []))

    # 推荐集：默认含 serial-monitor + workflow，叠加探测到的 skill
    available = set(_available_skills())
    recommended = {"serial-monitor", "workflow"}
    for _, _, skills in detected:
        recommended.update(skills)

    # 协议线索（粗扫 main.c，不递归）
    main_candidates = ["main.c", "Src/main.c", "Core/Src/main.c", "src/main.c", "main/main.c"]
    for rel in main_candidates:
        main_c = project / rel
        if main_c.is_file():
            try:
                text = main_c.read_text(encoding="utf-8", errors="ignore")
                if "FreeRTOS.h" in text or "rtthread.h" in text or "zephyr.h" in text:
                    recommended.add("rtos-debug")
                if "modbus" in text.lower() or 'mb.h' in text:
                    recommended.add("modbus-debug")
                if "CAN" in text and ("HAL_CAN" in text or "can_" in text.lower()):
                    recommended.add("can-debug")
                if "viOpen" in text or "viWrite" in text:
                    recommended.add("visa-debug")
            except OSError:
                pass
            break

    # 内存分析（几乎都能产 .map）
    recommended.add("memory-analysis")

    # 输出
    if not detected:
        print("  [!] 未识别出明确工程类型（构建系统 / 调试器 / 工具链 均未命中）\n")
    else:
        print("  检测到工程特征：")
        for category, label, _ in detected:
            print(f"    • {category}：{label}")
        print()

    # 过滤掉仓库里不存在的 skill
    rec_sorted = sorted(s for s in recommended if s in available)

    if not rec_sorted:
        print("  无可推荐的 skill（仓库可能未正确克隆）。")
        return

    print(f"  推荐安装集（{len(rec_sorted)} 个）：")
    print(f"    {' '.join(rec_sorted)}\n")

    print("  下一步操作：")
    print(f"    按推荐集安装：python3 scripts/install.py {project} --skills {' '.join(rec_sorted)}")
    print(f"    全量安装（{len(available)} 个）：python3 scripts/install.py {project} --yes")
    print(f"    查看全部 skill：python3 scripts/install.py --list")
    print(f"    只分析不安装：python3 scripts/install.py {project} --analyze")


def cmd_list() -> None:
    skills = _available_skills()
    if not skills:
        print("未找到可用 skill。")
        return
    print(f"可用 skill（共 {len(skills)} 个）：\n")
    max_name = max(len(s) for s in skills)
    for s in skills:
        desc = _read_skill_description(s)
        print(f"  {s:<{max_name}}  {desc}")


def cmd_install(project: Path, skill_names: list[str] | None, force: bool) -> None:
    available = _available_skills()
    if not available:
        print("错误：未在仓库中找到任何 skill。", file=sys.stderr)
        sys.exit(1)

    if skill_names:
        invalid = [s for s in skill_names if s not in available]
        if invalid:
            print(f"错误：以下 skill 不存在：{', '.join(invalid)}", file=sys.stderr)
            print(f"可用 skill：{', '.join(available)}", file=sys.stderr)
            sys.exit(1)
        to_install = skill_names
    else:
        to_install = available

    dest = _skills_dir(project)
    dest.mkdir(parents=True, exist_ok=True)

    total_copied = 0
    total_skipped = 0

    # 拷贝 skill 目录
    for skill in to_install:
        src = SKILLS_SRC / skill
        dst = dest / skill
        c, s = _copy_tree(src, dst, force)
        total_copied += c
        total_skipped += s
        status = "✓" if c > 0 else ("跳过" if s > 0 else "空")
        print(f"  {status} {skill} ({c} 文件)")

    # 拷贝 shared 目录
    if SHARED_SRC.is_dir():
        c, s = _copy_tree(SHARED_SRC, dest / "shared", force)
        total_copied += c
        total_skipped += s
        print(f"  {'✓' if c > 0 else '跳过'} shared ({c} 文件)")

    # 写入 meta
    meta = _load_meta(project)
    existing_skills = set(meta.get("skills", []))
    existing_skills.update(to_install)
    meta.update(
        {
            "source": "embed-ai-tool",
            "version": _git_short_hash(),
            "installed_at": datetime.now(timezone.utc).isoformat(),
            "skills": sorted(existing_skills),
        }
    )
    _save_meta(project, meta)

    print(f"\n安装完成：{total_copied} 文件已拷贝，{total_skipped} 文件已跳过。")
    print(f"目标目录：{dest}")
    if total_skipped > 0 and not force:
        print("提示：使用 --force 可覆盖已有文件。")


def cmd_uninstall(project: Path) -> None:
    dest = _skills_dir(project)
    meta = _load_meta(project)

    if not meta:
        # 没有 meta 文件，尝试列出疑似目录
        if dest.is_dir():
            dirs = [d.name for d in dest.iterdir() if d.is_dir()]
            if dirs:
                print("未找到安装记录（.em_skill_meta.json），但发现以下目录：")
                for d in sorted(dirs):
                    print(f"  - {d}")
                print("请手动确认并删除。")
                return
        print("未找到安装记录，也没有发现已安装的 skill。")
        return

    skills = meta.get("skills", [])
    removed = 0

    for skill in skills:
        skill_dir = dest / skill
        if skill_dir.is_dir():
            shutil.rmtree(skill_dir)
            print(f"  ✓ 已删除 {skill}")
            removed += 1

    # 删除 shared
    shared_dir = dest / "shared"
    if shared_dir.is_dir():
        shutil.rmtree(shared_dir)
        print("  ✓ 已删除 shared")

    # 删除 meta 文件
    mp = _meta_path(project)
    if mp.is_file():
        mp.unlink()

    # 如果 skills 目录为空，也删除
    if dest.is_dir() and not any(dest.iterdir()):
        dest.rmdir()

    print(f"\n卸载完成：已删除 {removed} 个 skill。")


def cmd_status(project: Path) -> None:
    meta = _load_meta(project)
    if not meta:
        print("未找到安装记录。该项目可能尚未安装 embed-ai-tool skill。")
        return

    print("embed-ai-tool 安装状态：\n")
    print(f"  版本：     {meta.get('version', '未知')}")
    print(f"  安装时间： {meta.get('installed_at', '未知')}")
    print(f"  来源：     {meta.get('source', '未知')}")

    skills = meta.get("skills", [])
    dest = _skills_dir(project)
    print(f"\n  已安装 skill（{len(skills)} 个）：")
    for s in skills:
        exists = (dest / s).is_dir()
        marker = "✓" if exists else "✗ (目录缺失)"
        print(f"    {marker} {s}")

    # 显示工具路径配置
    config_path = project / ".em_skill.json"
    if config_path.is_file():
        try:
            cfg = json.loads(config_path.read_text(encoding="utf-8"))
            tools = cfg.get("tools", {})
            if tools:
                print(f"\n  工具路径配置（{len(tools)} 个）：")
                for name, path in sorted(tools.items()):
                    print(f"    {name}: {path}")
        except (json.JSONDecodeError, OSError):
            pass


def cmd_detect(project: Path) -> None:
    print("探测工具路径...\n")

    # 复用 shared/tool_config.py 的逻辑
    sys.path.insert(0, str(SHARED_SRC))
    try:
        from tool_config import set_tool_path
    except ImportError:
        # 回退：直接写 .em_skill.json
        set_tool_path = None

    found = {}
    for tool in DETECT_TOOLS:
        path = shutil.which(tool)
        if path:
            found[tool] = path
            print(f"  ✓ {tool}: {path}")
        else:
            print(f"  ✗ {tool}: 未找到")

    if not found:
        print("\n未找到任何工具，请确认工具已安装并在 PATH 中。")
        return

    # 写入配置
    if set_tool_path:
        for tool, path in found.items():
            set_tool_path(tool, path, workspace=project)
    else:
        config_path = project / ".em_skill.json"
        cfg = {}
        if config_path.is_file():
            try:
                cfg = json.loads(config_path.read_text(encoding="utf-8"))
            except (json.JSONDecodeError, OSError):
                pass
        tools = cfg.setdefault("tools", {})
        tools.update(found)
        config_path.write_text(
            json.dumps(cfg, indent=2, ensure_ascii=False) + "\n",
            encoding="utf-8",
        )

    print(f"\n已将 {len(found)} 个工具路径写入 {project / '.em_skill.json'}")


# ── CLI ──────────────────────────────────────────────────────────────


def main() -> None:
    parser = argparse.ArgumentParser(
        description="embed-ai-tool 安装脚本",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument(
        "project",
        nargs="?",
        help="目标工程路径",
    )
    parser.add_argument(
        "--skills",
        nargs="+",
        metavar="SKILL",
        help="只安装指定 skill（默认行为已改为只分析不安装）",
    )
    parser.add_argument(
        "--yes",
        action="store_true",
        dest="yes_all",
        help="确认全量安装全部 skill（默认行为已改为只分析不安装）",
    )
    parser.add_argument(
        "--force",
        action="store_true",
        help="强制覆盖已有文件",
    )
    parser.add_argument(
        "--uninstall",
        action="store_true",
        help="卸载已安装的 skill",
    )
    parser.add_argument(
        "--list",
        action="store_true",
        dest="list_skills",
        help="列出仓库中所有可用 skill",
    )
    parser.add_argument(
        "--status",
        action="store_true",
        help="显示当前安装状态",
    )
    parser.add_argument(
        "--analyze",
        action="store_true",
        help="只分析工程类型并输出推荐集，不执行安装",
    )
    parser.add_argument(
        "--detect",
        action="store_true",
        help="安装后自动探测工具路径",
    )

    args = parser.parse_args()

    # --list 不需要 project 参数
    if args.list_skills:
        cmd_list()
        return

    if not args.project:
        parser.error("请指定目标工程路径（或使用 --list 查看可用 skill）。")

    project = Path(args.project).resolve()
    if not project.is_dir():
        print(f"错误：目录不存在：{project}", file=sys.stderr)
        sys.exit(1)

    if args.uninstall:
        cmd_uninstall(project)
        return

    if args.status:
        cmd_status(project)
        return

    if args.analyze:
        cmd_analyze(project)
        return

    # 默认行为：未指定 --skills 且未指定 --yes 时，只分析不安装
    if not args.skills and not args.yes_all:
        print("[!] 未指定 --skills 或 --yes，默认只执行工程分析，不写入任何文件。\n")
        cmd_analyze(project)
        return

    # 执行安装
    cmd_install(project, args.skills, args.force)

    if args.detect:
        print()
        cmd_detect(project)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3

from __future__ import annotations

import re
import sys
from pathlib import Path


REQUIRED_FILES = [
    ".gitignore",
    "README.md",
    "CONTRIBUTING.md",
    "shared/contracts.md",
    "shared/failure-taxonomy.md",
    "shared/platform-compatibility.md",
    "shared/references/tool-detection.md",
    "shared/references/acceptance-scenarios.md",
    "templates/skill-template/SKILL.md",
    "templates/skill-template/CHECKLIST.md",
    "templates/skill-template/SCENARIOS.md",
]

REQUIRED_SKILLS = [
    "build-cmake",
    "flash-openocd",
    "serial-monitor",
    "debug-gdb-openocd",
    "flash-jlink",
    "debug-jlink",
    "memory-analysis",
    "rtos-debug",
    "static-analysis",
]

REQUIRED_SECTIONS = [
    "## 适用场景",
    "## 必要输入",
    "## 自动探测",
    "## 执行步骤",
    "## 失败分流",
    "## 平台说明",
    "## 输出约定",
    "## 交接关系",
]


def fail(message: str, failures: list[str]) -> None:
    failures.append(message)


def validate_required_files(root: Path, failures: list[str]) -> None:
    for relative_path in REQUIRED_FILES:
        if not (root / relative_path).is_file():
            fail(f"missing file: {relative_path}", failures)


def parse_frontmatter(text: str) -> dict[str, str]:
    match = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
    if not match:
        return {}

    fields: dict[str, str] = {}
    for line in match.group(1).splitlines():
        if ":" not in line:
            continue
        key, value = line.split(":", 1)
        fields[key.strip()] = value.strip().strip('"')
    return fields


def validate_skill(skill_dir: Path, failures: list[str]) -> None:
    skill_md = skill_dir / "SKILL.md"
    if not skill_md.is_file():
        fail(f"missing file: {skill_md.relative_to(skill_dir.parent.parent)}", failures)
        return

    text = skill_md.read_text(encoding="utf-8")
    frontmatter = parse_frontmatter(text)
    expected_name = skill_dir.name

    if frontmatter.get("name") != expected_name:
        fail(
            f"{skill_md.relative_to(skill_dir.parent.parent)} frontmatter name should be '{expected_name}'",
            failures,
        )

    if not frontmatter.get("description"):
        fail(f"{skill_md.relative_to(skill_dir.parent.parent)} missing frontmatter description", failures)

    for heading in REQUIRED_SECTIONS:
        if heading not in text:
            fail(f"{skill_md.relative_to(skill_dir.parent.parent)} missing section: {heading}", failures)


def main() -> int:
    root = Path(__file__).resolve().parent.parent
    failures: list[str] = []

    validate_required_files(root, failures)

    for skill_name in REQUIRED_SKILLS:
        validate_skill(root / "skills" / skill_name, failures)

    if failures:
        print("Repository validation failed:")
        for failure in failures:
            print(f"- {failure}")
        return 1

    print("Repository validation passed.")
    print(f"Validated {len(REQUIRED_SKILLS)} skills and {len(REQUIRED_FILES)} shared files.")
    return 0


if __name__ == "__main__":
    sys.exit(main())

"""ESP-IDF 环境自动探测与激活。

统一提供 IDF 环境信息，替代各脚本中重复的 _find_idf_py()。
支持 v5.x (export.sh) 和 v6.0+ (EIM activate_idf_v*.sh) 两种安装方式。

用法::

    from idf_env import get_idf_env

    env = get_idf_env()
    if env is None:
        sys.exit("ESP-IDF 环境不可用")
    subprocess.run(env.idf_py_cmd + ["build"], env=env.env, cwd=project_dir)
"""

from __future__ import annotations

import os
import platform
import re
import shutil
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Any

# 同目录下的 tool_config
from tool_config import get_tool_path


@dataclass
class IdfEnv:
    """已激活的 ESP-IDF 环境快照。"""

    idf_py_cmd: list[str]  # e.g. ["python", "/path/to/idf.py"]
    env: dict[str, str]  # 完整环境变量，可直接传给 subprocess.run(env=)
    version: str | None  # e.g. "6.0"
    source: str  # "already-active" | "activate-script" | "export-sh" | "path"


# ---------------------------------------------------------------------------
# 模块级缓存
# ---------------------------------------------------------------------------
_cached_env: IdfEnv | None = None
_cached_resolved: bool = False


def get_idf_env() -> IdfEnv | None:
    """探测并返回可用的 IDF 环境，同一进程内缓存结果。"""
    global _cached_env, _cached_resolved
    if _cached_resolved:
        return _cached_env
    _cached_env = _resolve_idf_env()
    _cached_resolved = True
    return _cached_env


# ---------------------------------------------------------------------------
# 内部实现
# ---------------------------------------------------------------------------

def _resolve_idf_env() -> IdfEnv | None:
    """按优先级依次尝试各种方式获取 IDF 环境。"""

    # 1. 已激活：IDF_PATH 已设置且 idf.py 可达
    result = _try_already_active()
    if result:
        return result

    # 2. 通过激活脚本获取环境
    result = _try_activate_script()
    if result:
        return result

    # 3. idf.py 在 PATH 中（旧版安装或用户手动配置）
    result = _try_path_lookup()
    if result:
        return result

    return None


def _try_already_active() -> IdfEnv | None:
    """检查当前进程环境是否已激活 IDF。"""
    idf_path = os.environ.get("IDF_PATH")
    if not idf_path:
        return None

    idf_py = Path(idf_path) / "tools" / "idf.py"
    if not idf_py.exists():
        return None

    cmd = [sys.executable, str(idf_py)]
    env = dict(os.environ)
    version = _probe_version(cmd, env)
    return IdfEnv(idf_py_cmd=cmd, env=env, version=version, source="already-active")


def _try_activate_script() -> IdfEnv | None:
    """查找并 source 激活脚本，捕获激活后的环境变量。"""

    # 优先使用用户配置的路径
    configured = get_tool_path("idf-activate")
    if configured:
        script = Path(configured).expanduser()
        if script.exists():
            result = _source_and_capture(script)
            if result:
                return result

    is_win = platform.system() == "Windows"
    home = Path.home()

    # v6.0+ EIM 安装：~/.espressif/tools/activate_idf_v*.sh
    eim_dir = home / ".espressif" / "tools"
    if eim_dir.is_dir():
        if is_win:
            pattern = "activate_idf_v*.ps1"
        else:
            pattern = "activate_idf_v*.sh"
        scripts = sorted(eim_dir.glob(pattern), reverse=True)
        for script in scripts:
            result = _source_and_capture(script)
            if result:
                result.source = "activate-script"
                return result

    # v5.x：常见路径下的 export.sh
    export_candidates: list[Path] = []
    idf_path_env = os.environ.get("IDF_PATH")
    if idf_path_env:
        export_candidates.append(Path(idf_path_env) / ("export.ps1" if is_win else "export.sh"))

    for candidate_dir in [home / "esp" / "esp-idf", home / "esp-idf", Path("/opt/esp-idf")]:
        export_candidates.append(candidate_dir / ("export.ps1" if is_win else "export.sh"))

    for script in export_candidates:
        if script.exists():
            result = _source_and_capture(script)
            if result:
                result.source = "export-sh"
                return result

    return None


def _try_path_lookup() -> IdfEnv | None:
    """尝试从 PATH 或 tool_config 配置中找到 idf.py。"""
    env = dict(os.environ)

    # tool_config 配置
    configured = get_tool_path("idf-py")
    if configured and shutil.which(configured):
        cmd = configured.split()
        version = _probe_version(cmd, env)
        return IdfEnv(idf_py_cmd=cmd, env=env, version=version, source="path")

    # PATH 中直接可用
    if shutil.which("idf.py"):
        cmd = ["idf.py"]
        version = _probe_version(cmd, env)
        return IdfEnv(idf_py_cmd=cmd, env=env, version=version, source="path")

    return None


def _source_and_capture(script: Path) -> IdfEnv | None:
    """Source 一个 shell 脚本并捕获激活后的完整环境变量。"""
    system = platform.system()

    if system == "Windows":
        return _source_windows(script)
    else:
        return _source_posix(script)


def _source_posix(script: Path) -> IdfEnv | None:
    """在 bash 子进程中 source 脚本，用 env -0 捕获环境。"""
    try:
        result = subprocess.run(
            ["bash", "-c", f'source "{script}" > /dev/null 2>&1 && env -0'],
            capture_output=True, timeout=30,
        )
    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
        return None

    if result.returncode != 0:
        return None

    env = _parse_env0(result.stdout)
    if not env:
        return None

    return _build_env_from_captured(env)


def _source_windows(script: Path) -> IdfEnv | None:
    """在 PowerShell / cmd 子进程中执行激活脚本并捕获环境。"""
    suffix = script.suffix.lower()
    try:
        if suffix == ".ps1":
            cmd_line = (
                f'. "{script}" | Out-Null; '
                'Get-ChildItem Env: | ForEach-Object { "$($_.Name)=$($_.Value)" }'
            )
            result = subprocess.run(
                ["powershell", "-NoProfile", "-Command", cmd_line],
                capture_output=True, text=True, timeout=30,
            )
        elif suffix == ".bat":
            cmd_line = f'call "{script}" > nul 2>&1 && set'
            result = subprocess.run(
                ["cmd", "/c", cmd_line],
                capture_output=True, text=True, timeout=30,
            )
        else:
            return None
    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
        return None

    if result.returncode != 0:
        return None

    env = _parse_env_text(result.stdout)
    if not env:
        return None

    return _build_env_from_captured(env)


def _build_env_from_captured(env: dict[str, str]) -> IdfEnv | None:
    """从捕获的环境变量中构造 IdfEnv。"""
    idf_path = env.get("IDF_PATH")
    if not idf_path:
        return None

    idf_py = Path(idf_path) / "tools" / "idf.py"
    if not idf_py.exists():
        return None

    # 使用捕获环境中的 python，回退到当前解释器
    python = env.get("IDF_PYTHON_ENV_PATH")
    if python:
        python_bin = Path(python) / "bin" / "python"
        if not python_bin.exists():
            python_bin = Path(python) / "Scripts" / "python.exe"
        if python_bin.exists():
            cmd = [str(python_bin), str(idf_py)]
        else:
            cmd = [sys.executable, str(idf_py)]
    else:
        cmd = [sys.executable, str(idf_py)]

    version = _probe_version(cmd, env)
    return IdfEnv(idf_py_cmd=cmd, env=env, version=version, source="activate-script")


def _probe_version(cmd: list[str], env: dict[str, str]) -> str | None:
    """运行 idf.py --version 获取版本号。"""
    try:
        result = subprocess.run(
            cmd + ["--version"],
            capture_output=True, text=True, timeout=10, env=env,
        )
        if result.returncode == 0:
            text = result.stdout.strip()
            # 提取类似 "v5.3" 或 "ESP-IDF v5.3-dev-..."
            m = re.search(r"v?(\d+\.\d+)", text)
            return m.group(1) if m else text
    except Exception:
        pass
    return env.get("ESP_IDF_VERSION")


def _parse_env0(raw: bytes) -> dict[str, str]:
    """解析 env -0 的 NUL 分隔输出。"""
    env: dict[str, str] = {}
    for entry in raw.split(b"\x00"):
        if not entry:
            continue
        try:
            decoded = entry.decode("utf-8", errors="replace")
        except Exception:
            continue
        eq = decoded.find("=")
        if eq > 0:
            env[decoded[:eq]] = decoded[eq + 1 :]
    return env


def _parse_env_text(text: str) -> dict[str, str]:
    """解析 KEY=VALUE 格式的文本环境变量输出（Windows set / PowerShell）。"""
    env: dict[str, str] = {}
    for line in text.splitlines():
        eq = line.find("=")
        if eq > 0:
            env[line[:eq]] = line[eq + 1 :]
    return env

"""统一项目探测模块。

供新 skill 调用，自动识别构建系统、目标芯片、RTOS 和调试探针。
现有 skill 不做改动，仅新 skill 引用本模块。
"""

from __future__ import annotations

import json
import os
import re
import shutil
import subprocess
from pathlib import Path
from typing import Any


def detect_build_system(workspace: Path) -> str | None:
    markers = [
        ("CMakeLists.txt", "cmake"),
        ("platformio.ini", "platformio"),
        ("sdkconfig", "idf"),
    ]
    for filename, system in markers:
        if (workspace / filename).exists():
            return system

    for f in workspace.iterdir():
        if f.is_file():
            ext = f.suffix.lower()
            if ext == ".uvprojx":
                return "keil"
            if ext in (".eww", ".ewp"):
                return "iar"

    # Makefile 检测 — 最低优先级，仅在其他系统均未匹配时使用
    for mf_name in ("Makefile", "makefile", "GNUmakefile"):
        if (workspace / mf_name).is_file():
            return "makefile"

    return None


def detect_target_mcu(workspace: Path, build_system: str | None) -> str | None:
    if build_system == "keil":
        for f in workspace.glob("*.uvprojx"):
            try:
                text = f.read_text(encoding="utf-8", errors="ignore")
                m = re.search(r"<Device>(.*?)</Device>", text)
                if m:
                    return m.group(1)
            except OSError:
                pass

    if build_system == "iar":
        for f in workspace.glob("*.ewp"):
            try:
                text = f.read_text(encoding="utf-8", errors="ignore")
                m = re.search(r"<OGChipSelectEditMenu>(.*?)</OGChipSelectEditMenu>", text)
                if m:
                    return m.group(1).split("\t")[0] if "\t" in m.group(1) else m.group(1)
            except OSError:
                pass

    if build_system == "platformio":
        ini = workspace / "platformio.ini"
        if ini.is_file():
            try:
                text = ini.read_text(encoding="utf-8", errors="ignore")
                m = re.search(r"board\s*=\s*(\S+)", text)
                if m:
                    return m.group(1)
            except OSError:
                pass

    if build_system == "idf":
        sdkconfig = workspace / "sdkconfig"
        if sdkconfig.is_file():
            try:
                text = sdkconfig.read_text(encoding="utf-8", errors="ignore")
                m = re.search(r'CONFIG_IDF_TARGET="(\S+)"', text)
                if m:
                    return m.group(1)
            except OSError:
                pass

    if build_system == "makefile":
        for mf_name in ("Makefile", "makefile", "GNUmakefile"):
            mf = workspace / mf_name
            if mf.is_file():
                try:
                    text = mf.read_text(encoding="utf-8", errors="ignore")
                    m = re.search(r"(?:^|\n)MCU\s*[:?]?=\s*(\S+)", text)
                    if m:
                        return m.group(1).strip()
                    m = re.search(r"-mcpu=([a-z0-9]+)", text)
                    if m:
                        return m.group(1)
                except OSError:
                    pass
                break

    return None


def detect_rtos(workspace: Path) -> str | None:
    rtos_headers = {
        "FreeRTOS.h": "freertos",
        "rtthread.h": "rt-thread",
        "zephyr/kernel.h": "zephyr",
    }
    rtos_symbols = {
        "vTaskStartScheduler": "freertos",
        "rt_thread_init": "rt-thread",
        "k_thread_create": "zephyr",
    }

    for root, _dirs, files in os.walk(workspace):
        depth = str(root).replace(str(workspace), "").count(os.sep)
        if depth > 4:
            continue
        for fname in files:
            if not fname.endswith((".c", ".h", ".cpp")):
                continue
            fpath = Path(root) / fname
            try:
                text = fpath.read_text(encoding="utf-8", errors="ignore")
            except OSError:
                continue
            for header, rtos in rtos_headers.items():
                if f'#include "{header}"' in text or f"#include <{header}>" in text:
                    return rtos
            for symbol, rtos in rtos_symbols.items():
                if symbol in text:
                    return rtos
    return None


def detect_probes() -> list[str]:
    probes: list[str] = []
    if shutil.which("JLinkExe") or shutil.which("JLink.exe"):
        probes.append("jlink")
    if shutil.which("openocd"):
        probes.append("openocd")
    if shutil.which("pyocd"):
        probes.append("pyocd")
    return probes


def _find_artifacts(workspace: Path) -> list[dict[str, str]]:
    artifacts: list[dict[str, str]] = []
    build_dirs = ["build", "Build", "output", "Output", "Debug", "Release", ".pio/build"]
    ext_map = {".elf": "elf", ".hex": "hex", ".bin": "bin", ".axf": "elf"}

    for bd_name in build_dirs:
        bd = workspace / bd_name
        if not bd.is_dir():
            continue
        for root, _dirs, files in os.walk(bd):
            for fname in files:
                ext = Path(fname).suffix.lower()
                kind = ext_map.get(ext)
                if kind:
                    artifacts.append({
                        "path": str(Path(root) / fname),
                        "kind": kind,
                    })
    return artifacts


def detect_project(workspace: Path) -> dict[str, Any]:
    build_system = detect_build_system(workspace)
    target_mcu = detect_target_mcu(workspace, build_system)
    rtos = detect_rtos(workspace)
    probes = detect_probes()
    artifacts = _find_artifacts(workspace)

    profile: dict[str, Any] = {
        "workspace_root": str(workspace),
        "workspace_os": _detect_os(),
    }
    if build_system:
        profile["build_system"] = build_system
    if target_mcu:
        profile["target_mcu"] = target_mcu
    if rtos:
        profile["rtos"] = rtos
    if probes:
        profile["probes"] = probes
    if artifacts:
        elf_arts = [a for a in artifacts if a["kind"] == "elf"]
        best = elf_arts[0] if elf_arts else artifacts[0]
        profile["artifact_path"] = best["path"]
        profile["artifact_kind"] = best["kind"]
        profile["all_artifacts"] = artifacts

    return profile


def _detect_os() -> str:
    import platform as _platform
    system = _platform.system().lower()
    if system == "darwin":
        return "macos"
    if system == "windows":
        return "windows"
    return "linux"

"""轻量工具路径持久化配置层。

提供 JSON 配置文件的读写，支持工作区级（.em_skill.json）和全局级
（~/.config/em_skill/config.json）两层配置，工作区覆盖全局。

解析优先级（由各脚本自行实现）：
  CLI 参数 → 配置文件 → 环境变量 → 硬编码路径 → PATH
"""

from __future__ import annotations

import json
import os
import platform
from pathlib import Path
from typing import Any

CONFIG_FILENAME = ".em_skill.json"


def user_config_path() -> Path:
    """返回全局配置文件路径（XDG / APPDATA）。"""
    if platform.system() == "Windows":
        base = os.environ.get("APPDATA")
        if base:
            return Path(base) / "em_skill" / "config.json"
    # XDG_CONFIG_HOME 或 ~/.config
    base = os.environ.get("XDG_CONFIG_HOME", "")
    if not base:
        base = str(Path.home() / ".config")
    return Path(base) / "em_skill" / "config.json"


def workspace_config_path(workspace: str | Path | None = None) -> Path:
    """返回工作区级配置文件路径。"""
    ws = Path(workspace) if workspace else Path.cwd()
    return ws / CONFIG_FILENAME


def load_config(path: Path) -> dict[str, Any]:
    """读取 JSON 配置文件，文件不存在或格式错误时返回空字典。"""
    if not path.is_file():
        return {}
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError):
        return {}


def save_config(path: Path, data: dict[str, Any]) -> None:
    """将配置写入 JSON 文件，自动创建父目录。"""
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
        encoding="utf-8",
    )


def get_tool_path(
    tool_name: str,
    workspace: str | Path | None = None,
) -> str | None:
    """合并读取工具路径（工作区优先于全局）。"""
    # 工作区级
    ws_cfg = load_config(workspace_config_path(workspace))
    ws_path = ws_cfg.get("tools", {}).get(tool_name)
    if ws_path:
        return ws_path

    # 全局级
    global_cfg = load_config(user_config_path())
    return global_cfg.get("tools", {}).get(tool_name)


def set_tool_path(
    tool_name: str,
    tool_path: str,
    workspace: str | Path | None = None,
    global_: bool = False,
) -> Path:
    """写入工具路径到指定级别的配置文件，返回写入的文件路径。"""
    cfg_path = user_config_path() if global_ else workspace_config_path(workspace)
    data = load_config(cfg_path)
    tools = data.setdefault("tools", {})
    tools[tool_name] = tool_path
    save_config(cfg_path, data)
    return cfg_path


def remove_tool_path(
    tool_name: str,
    workspace: str | Path | None = None,
    global_: bool = False,
) -> bool:
    """从配置中删除工具路径，返回是否实际删除了条目。"""
    cfg_path = user_config_path() if global_ else workspace_config_path(workspace)
    data = load_config(cfg_path)
    tools = data.get("tools", {})
    if tool_name not in tools:
        return False
    del tools[tool_name]
    save_config(cfg_path, data)
    return True


def list_tools(
    workspace: str | Path | None = None,
) -> dict[str, dict[str, str]]:
    """列出所有已配置的工具，返回 {tool_name: {"path": ..., "source": ...}}。"""
    result: dict[str, dict[str, str]] = {}

    global_cfg = load_config(user_config_path())
    for name, path in global_cfg.get("tools", {}).items():
        result[name] = {"path": path, "source": "global"}

    ws_cfg = load_config(workspace_config_path(workspace))
    for name, path in ws_cfg.get("tools", {}).items():
        result[name] = {"path": path, "source": "workspace"}

    return result


def find_sdk_bundled_openocd_scripts() -> str | None:
    """探测嵌入式 SDK 自带的 OpenOCD scripts 目录。
    
    部分 SDK（如 Raspberry Pi Pico SDK、PlatformIO 等）会安装
    自己的 OpenOCD，包含芯片特定目标配置文件（系统 OpenOCD 可能没有）。
    返回 scripts 目录路径，找不到返回 None。
    
    跨平台：Windows 用 openocd.exe，macOS/Linux 用 bin/openocd。
    """
    import sys as _sys
    sdk_dir = Path.home() / ".pico-sdk" / "openocd"
    if not sdk_dir.exists():
        return None
    for version_dir in sorted(sdk_dir.iterdir(), reverse=True):
        if not version_dir.is_dir():
            continue
        # Binaries can be in root (Windows) or bin/ (Unix)
        ocd = version_dir / "openocd.exe" if _sys.platform == "win32" else version_dir / "bin" / "openocd"
        if not ocd.exists() and _sys.platform != "win32":
            ocd = version_dir / "openocd"
        if not ocd.exists():
            continue
        scripts = version_dir / "scripts"
        if scripts.is_dir():
            return str(scripts)
    return None