qa-agent-kit 0.6.0__py3-none-any.whl

qakit/tools/install_skills.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Link the QAKit skills into the folder each AI coding tool reads, so one checkout serves them all.
+
+  python3 tools/install_skills.py --target claude --scope project          # <cwd>/.claude/skills/<skill> -> this checkout
+  python3 tools/install_skills.py --target all --scope user                # ~/.claude/skills, ~/.agents/skills, ~/.cursor/rules, ~/.gemini
+  python3 tools/install_skills.py --target codex --scope project --project /path/to/repo
+  python3 tools/install_skills.py --target claude --scope project --uninstall
+
+Targets and what they get:
+  claude   .claude/skills/<skill>  -> symlink to skills/<skill> (Claude Code loads SKILL.md from there)
+  codex    .agents/skills/<skill>  -> symlink (Codex CLI skills folder); plus AGENTS.md gets a pointer line when the project has one
+  cursor   .cursor/rules/qakit-<skill>.mdc -> a rule file that tells Cursor to read the SKILL.md
+  gemini   GEMINI.md (project) or ~/.gemini/GEMINI.md (user) gets a pointer line
+Existing files that are not QAKit links are left alone and reported. Idempotent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+KIT = Path(__file__).resolve().parents[1]
+SKILLS = sorted(p.parent.name for p in (KIT / "skills").glob("*/SKILL.md"))
+POINTER = "QAKit (QA agent kit): read {path} before QA work; procedures in {skills}.\n"
+
+
+def targets_for(name: str, scope: str, project: Path, home: Path) -> list[tuple[str, Path, Path | None]]:
+    """(kind, destination, source) per skill: kind 'link' symlinks a folder, 'rule' writes a Cursor rule, 'pointer' appends a line."""
+    base = project if scope == "project" else home
+    out: list[tuple[str, Path, Path | None]] = []
+    if name == "claude":
+        out += [("link", base / ".claude/skills" / s, KIT / "skills" / s) for s in SKILLS]
+    elif name == "codex":
+        out += [("link", base / ".agents/skills" / s, KIT / "skills" / s) for s in SKILLS]
+        if scope == "project":
+            out.append(("pointer", base / "AGENTS.md", None))
+    elif name == "cursor":
+        out += [("rule", base / ".cursor/rules" / f"qakit-{s}.mdc", KIT / "skills" / s / "SKILL.md") for s in SKILLS]
+    elif name == "gemini":
+        out.append(("pointer", base / "GEMINI.md" if scope == "project" else home / ".gemini/GEMINI.md", None))
+    else:
+        raise SystemExit(f"unknown target {name}")
+    return out
+
+
+def rule_text(skill_md: Path) -> str:
+    name = skill_md.parent.name
+    return f"---\ndescription: QAKit {name} procedure\nalwaysApply: false\n---\nBefore QA work of this kind, read and follow {skill_md} (QAKit, {KIT}).\n"
+
+
+def pointer_line() -> str:
+    return POINTER.format(path=KIT / "AGENTS.md", skills=KIT / "skills")
+
+
+def apply(kind: str, dest: Path, source: Path | None, uninstall: bool) -> str:
+    if kind == "link":
+        if dest.is_symlink():
+            if os.path.realpath(dest) != os.path.realpath(source):
+                return f"skip   {dest} (symlink to something else)"
+            if uninstall:
+                dest.unlink()
+                return f"removed {dest}"
+            return f"ok     {dest}"
+        if dest.exists():
+            return f"skip   {dest} (exists and is not a QAKit link)"
+        if uninstall:
+            return f"absent {dest}"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.symlink_to(source, target_is_directory=True)   # mutation-ok: the flag only matters on Windows
+        return f"linked {dest} -> {source}"
+    if kind == "rule":
+        text = rule_text(source)
+        if uninstall:
+            if dest.is_file() and "QAKit" in dest.read_text(encoding="utf-8"):
+                dest.unlink()
+                return f"removed {dest}"
+            return f"absent {dest}"
+        if dest.is_file() and dest.read_text(encoding="utf-8") == text:
+            return f"ok     {dest}"
+        if dest.is_file() and "QAKit" not in dest.read_text(encoding="utf-8"):
+            return f"skip   {dest} (exists and is not a QAKit rule)"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(text, encoding="utf-8")
+        return f"wrote  {dest}"
+    if kind == "pointer":
+        line = pointer_line()
+        existing = dest.read_text(encoding="utf-8") if dest.is_file() else ""
+        if uninstall:
+            if line in existing:
+                dest.write_text(existing.replace(line, ""), encoding="utf-8")
+                return f"removed pointer in {dest}"
+            return f"absent {dest}"
+        if line in existing:
+            return f"ok     {dest}"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(existing + ("\n" if existing and not existing.endswith("\n") else "") + line, encoding="utf-8")
+        return f"added  pointer in {dest}"
+    raise SystemExit(kind)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--target", action="append", choices=["claude", "codex", "cursor", "gemini", "all"], required=True)
+    parser.add_argument("--scope", choices=["project", "user"], default="project")
+    parser.add_argument("--project", default=".", help="project folder for --scope project (default: cwd)")
+    parser.add_argument("--home", default=str(Path.home()), help=argparse.SUPPRESS)
+    parser.add_argument("--uninstall", action="store_true")
+    args = parser.parse_args(argv)
+    names = ["claude", "codex", "cursor", "gemini"] if "all" in args.target else args.target
+    project, home = Path(args.project).resolve(), Path(args.home).resolve()
+    for name in names:
+        for kind, dest, source in targets_for(name, args.scope, project, home):
+            print(apply(kind, dest, source, args.uninstall))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())   # mutation-ok: entry point, main() always returns 0