agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/cli/release.py

@@ -0,0 +1,178 @@
+"""
+release — Generate release artifacts and checksums without publishing.
+
+Usage:
+    agent-toolkit release --dry-run [--output DIR] [--target all]
+
+Options:
+    --dry-run       Required: prevents accidental publishing
+    --output DIR    Output directory (default: dist/)
+    --target TARGET Specific target or 'all' (default: all)
+    --json          JSON output
+    --help          Show this help
+
+Example:
+    agent-toolkit release --dry-run --output dist/
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+from agent_toolkit._paths import toolkit_root
+
+
+def _file_digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _find_repo_root() -> Path:
+    root = toolkit_root()
+    if (root / "distributions").is_dir():
+        return root
+    if (root.parent / "distributions").is_dir():
+        return root.parent
+    return root
+
+
+def cmd_release(args: list[str]) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="agent-toolkit release", add_help=False)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        required=True,
+        help="Required: prevents accidental publishing",
+    )
+    parser.add_argument("--output", default="dist/")
+    parser.add_argument("--target", default="all")
+    parser.add_argument("--json", dest="json_out", action="store_true")
+    parser.add_argument("--help", "-h", action="store_true")
+    parsed, _ = parser.parse_known_args(args)
+
+    if parsed.help:
+        print(__doc__)
+        return 0
+
+    if not parsed.dry_run:
+        print("  ✗  --dry-run is required to prevent accidental publishing", file=sys.stderr)
+        return 1
+
+    repo_root = _find_repo_root()
+    output_dir = Path(parsed.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        import yaml  # noqa: F401
+
+        from agent_toolkit.compiler.loader import load_graph
+    except ImportError as e:
+        print(f"  ✗  Compiler unavailable: {e}", file=sys.stderr)
+        return 1
+
+    graph = load_graph(repo_root)
+    if graph.errors:
+        for err in graph.errors:
+            print(f"  ✗  {err}", file=sys.stderr)
+        return 1
+
+    json_mode = parsed.json_out
+
+    def _say(*args, **kwargs):
+        if not json_mode:
+            print(*args, **kwargs)
+
+    _say(f"\nRelease dry run — output: {output_dir}\n")
+
+    targets = {
+        "claude-code": "agent_toolkit.compiler.targets.claude_code.ClaudeCodeAdapter",
+        "cursor": "agent_toolkit.compiler.targets.cursor.CursorAdapter",
+        "opencode": "agent_toolkit.compiler.targets.opencode.OpenCodeAdapter",
+        "copilot-cli": "agent_toolkit.compiler.targets.copilot.CopilotCLIAdapter",
+        "copilot-repository": "agent_toolkit.compiler.targets.copilot.CopilotRepositoryAdapter",
+        "gemini-cli": "agent_toolkit.compiler.targets.gemini_cli.GeminiCLIAdapter",
+        "windsurf": "agent_toolkit.compiler.targets.windsurf.WindsurfAdapter",
+        "pi": "agent_toolkit.compiler.targets.pi.PiAdapter",
+        "codex": "agent_toolkit.compiler.targets.codex.CodexAdapter",
+    }
+
+    target_filter = parsed.target
+    if target_filter != "all":
+        targets = {k: v for k, v in targets.items() if k == target_filter}
+
+    artifacts_summary = []
+    checksums: dict[str, str] = {}
+
+    for target_id, adapter_path in targets.items():
+        try:
+            module_path, cls_name = adapter_path.rsplit(".", 1)
+            import importlib
+
+            mod = importlib.import_module(module_path)
+            AdapterCls = getattr(mod, cls_name)
+        except (ImportError, AttributeError):
+            _say(f"  ⚠  {target_id}: adapter not available — skipping")
+            continue
+
+        target_out = output_dir / target_id
+        target_out.mkdir(parents=True, exist_ok=True)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            adapter = AdapterCls(Path(tmpdir), repo_root)
+            for product in graph.products.values():
+                result = adapter.compile(graph, product)
+                if result.errors:
+                    print(f"  ✗  {target_id}/{product.id}: {result.errors}", file=sys.stderr)
+                    continue
+
+                # Create tarball
+                tarball = target_out / f"{product.id}.tar.gz"
+                product_dir = Path(tmpdir) / product.id
+                if product_dir.is_dir():
+                    with tarfile.open(tarball, "w:gz") as tar:
+                        tar.add(product_dir, arcname=product.id)
+                    digest = _file_digest(tarball)
+                    checksums[str(tarball.relative_to(output_dir))] = digest
+                    artifacts_summary.append(
+                        {
+                            "target": target_id,
+                            "product": product.id,
+                            "artifact": str(tarball),
+                            "digest": digest,
+                        }
+                    )
+                    _say(f"  ✓  {target_id}/{product.id} → {tarball.name}")
+
+    # Write checksums
+    checksums_dir = output_dir / "checksums"
+    checksums_dir.mkdir(exist_ok=True)
+    checksums_file = checksums_dir / "SHA256SUMS"
+    with checksums_file.open("w") as f:
+        for path, digest in sorted(checksums.items()):
+            f.write(f"{digest}  {path}\n")
+
+    # Write release manifest
+    manifests_dir = output_dir / "manifests"
+    manifests_dir.mkdir(exist_ok=True)
+    manifest = {
+        "targets": list(targets.keys()),
+        "products": list(graph.products.keys()),
+        "artifactCount": len(artifacts_summary),
+    }
+    (manifests_dir / "release-manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+
+    _say(f"\n  ✓  {len(artifacts_summary)} artifacts generated")
+    _say(f"  ✓  Checksums: {checksums_file}")
+    _say(f"  ✓  Manifest: {manifests_dir / 'release-manifest.json'}")
+    _say("\n  ℹ  Dry run complete — nothing published\n")
+
+    if json_mode:
+        print(json.dumps(artifacts_summary, indent=2))
+
+    return 0

agent_toolkit/cli/skills.py

@@ -0,0 +1,461 @@
+"""
+skills — Skill management for agent-toolkit.
+
+Usage:
+    agent-toolkit skills <subcommand> [options]
+
+Subcommands:
+    list [--domain DOMAIN]     List skills grouped by domain
+    sync [--tools TOOLS]       Sync skills to tool-specific directories
+    validate                   Validate SKILL.md frontmatter
+
+Options:
+    --domain DOMAIN   Filter by domain (used with list)
+    --tools TOOLS     Comma-separated tools to sync (used with sync)
+                      Valid: claude-code, cursor, opencode
+    --help            Show this help message
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+
+# Windows: force UTF-8 output so Unicode chars (✓ ✗ ──) don't crash
+import sys as _sys
+from pathlib import Path
+
+from agent_toolkit._paths import toolkit_root
+
+if _sys.platform == "win32":
+    try:
+        _sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        _sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+def _parse_skill_description(skill_dir):
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return ""
+    text = skill_md.read_text(errors="replace")
+    fm_match = re.match(r"^---[ \t]*\n(.*?)\n---", text, re.DOTALL)
+    if not fm_match:
+        return ""
+    fm = fm_match.group(1)
+    # Block scalar: description: >-\n  content
+    block = re.search(r"^description:[ \t]*[|>][\-+]?[ \t]*\n((?:[ \t]+.+\n?)+)", fm, re.MULTILINE)
+    if block:
+        lines = [line.strip() for line in block.group(1).splitlines() if line.strip()]
+        return " ".join(lines)[:120]
+    # Inline: description: text
+    inline = re.search(r"^description:[ \t]+(.+)$", fm, re.MULTILINE)
+    if inline:
+        return inline.group(1).strip()[:120]
+    return ""
+
+
+def _load_layout(toolkit_dir: Path) -> dict | None:
+    layout_path = toolkit_dir / "catalogs" / "skills-layout.json"
+    if not layout_path.exists():
+        print(f"  ✗  skills-layout.json not found: {layout_path}", file=sys.stderr)
+        return None
+    try:
+        return json.loads(layout_path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"  ✗  Cannot parse skills-layout.json: {exc}", file=sys.stderr)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# SKILL.md frontmatter parsing (stdlib-only, no PyYAML)
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_SIMPLE_KV_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$")
+
+
+def _parse_frontmatter_simple(content: str) -> dict | None:
+    """Parse YAML frontmatter — handles inline values and block scalars (>-, |-)."""
+    match = _FRONTMATTER_RE.match(content)
+    if not match:
+        return None
+    result: dict[str, str] = {}
+    lines = match.group(1).splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+        m = _SIMPLE_KV_RE.match(stripped)
+        if m:
+            key = m.group(1).strip()
+            val = m.group(2).strip().strip('"').strip("'")
+            # YAML block scalar — collect indented lines that follow
+            if val in (">", ">-", "|-", "|", ">+", "|+"):
+                block_lines = []
+                j = i + 1
+                while j < len(lines) and (lines[j].startswith(" ") or lines[j].startswith("\t")):
+                    block_lines.append(lines[j].strip())
+                    j += 1
+                result[key] = " ".join(block_lines)
+                i = j
+                continue
+            result[key] = val
+        i += 1
+    return result
+
+
+# ---------------------------------------------------------------------------
+# list subcommand
+# ---------------------------------------------------------------------------
+
+
+def _cmd_list(args: list[str], toolkit_dir: Path) -> int:
+    """Display skills grouped by domain."""
+    domain_filter: str | None = None
+    i = 0
+    while i < len(args):
+        if args[i] == "--domain" and i + 1 < len(args):
+            domain_filter = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    layout = _load_layout(toolkit_dir)
+    if layout is None:
+        return 1
+
+    groups: dict[str, list[str]] = layout.get("groups", {})
+    skills_index: dict[str, dict] = {s["name"]: s for s in layout.get("skills", [])}
+
+    if domain_filter and domain_filter not in groups:
+        available = ", ".join(sorted(groups.keys()))
+        print(f"  ✗  Unknown domain: {domain_filter}  (available: {available})", file=sys.stderr)
+        return 1
+
+    targets = {domain_filter: groups[domain_filter]} if domain_filter else groups
+
+    print()
+    print("Available skills")
+    print()
+
+    for domain, skill_names in sorted(targets.items()):
+        print(f"── {domain} ──")
+        for name in sorted(skill_names):
+            info = skills_index.get(name, {})
+            path = toolkit_dir / info.get("path", f"skills/{domain}/{name}")
+            skill_md = path / "SKILL.md"
+
+            description = ""
+            if skill_md.exists():
+                try:
+                    content = skill_md.read_text(errors="replace")
+                    fm = _parse_frontmatter_simple(content)
+                    if fm:
+                        description = fm.get("description", "")
+                except OSError:
+                    pass
+
+            exists_marker = "✓" if skill_md.exists() else "✗"
+            desc_str = f"  — {description}" if description else ""
+            print(f"  {exists_marker}  {name:<40}{desc_str}")
+        print()
+
+    total = sum(len(v) for v in groups.values())
+    print(f"Total: {total} skill(s) across {len(groups)} domain(s)")
+    print()
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# sync subcommand
+# ---------------------------------------------------------------------------
+
+
+def _sync_claude_code(toolkit_dir: Path) -> bool:
+    """Copy/symlink SKILL.md files into ~/.claude/skills/<name>/."""
+    skills_dir = toolkit_dir / "skills"
+    if not skills_dir.is_dir():
+        print(f"  ✗  Skills directory not found: {skills_dir}", file=sys.stderr)
+        return False
+
+    dst_root = Path.home() / ".claude" / "skills"
+    success = True
+
+    for skill_md in sorted(skills_dir.rglob("SKILL.md")):
+        skill_dir = skill_md.parent
+        name = skill_dir.name
+        dst = dst_root / name / "SKILL.md"
+        try:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            if dst.exists() and dst.read_bytes() == skill_md.read_bytes():
+                print(f"  -  {name}: already up to date")
+                continue
+            shutil.copy2(skill_md, dst)
+            print(f"  ✓  {name}: synced → {dst}")
+        except (PermissionError, OSError) as exc:
+            print(f"  ✗  {name}: {exc}", file=sys.stderr)
+            success = False
+
+    return success
+
+
+def _sync_cursor(toolkit_dir: Path) -> bool:
+    """Write a skills index JSON to ~/.cursor/skills-index.json."""
+    layout = _load_layout(toolkit_dir)
+    if layout is None:
+        return False
+
+    index: list[dict] = []
+    for skill_info in layout.get("skills", []):
+        name = skill_info["name"]
+        path = toolkit_dir / skill_info.get("path", f"skills/{skill_info.get('group', '')}/{name}")
+        skill_md = path / "SKILL.md"
+        description = ""
+        if skill_md.exists():
+            try:
+                fm = _parse_frontmatter_simple(skill_md.read_text(errors="replace"))
+                if fm:
+                    description = fm.get("description", "")
+            except OSError:
+                pass
+        index.append(
+            {
+                "name": name,
+                "group": skill_info.get("group", ""),
+                "description": description,
+                "path": str(path),
+            }
+        )
+
+    dst = Path.home() / ".cursor" / "skills-index.json"
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_text(json.dumps({"skills": index}, indent=2) + "\n")
+        print(f"  ✓  cursor: skills-index written → {dst} ({len(index)} skills)")
+        return True
+    except (PermissionError, OSError) as exc:
+        print(f"  ✗  cursor: {exc}", file=sys.stderr)
+        return False
+
+
+def _sync_opencode(toolkit_dir: Path) -> bool:
+    """Copy SKILL.md files to ~/.config/opencode/skills/<name>/."""
+    skills_dir = toolkit_dir / "skills"
+    if not skills_dir.is_dir():
+        print(f"  ✗  Skills directory not found: {skills_dir}", file=sys.stderr)
+        return False
+
+    dst_root = Path.home() / ".config" / "opencode" / "skills"
+    success = True
+
+    for skill_md in sorted(skills_dir.rglob("SKILL.md")):
+        skill_dir = skill_md.parent
+        name = skill_dir.name
+        dst = dst_root / name / "SKILL.md"
+        try:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            if dst.exists() and dst.read_bytes() == skill_md.read_bytes():
+                print(f"  -  {name}: already up to date")
+                continue
+            shutil.copy2(skill_md, dst)
+            print(f"  ✓  {name}: synced → {dst}")
+        except (PermissionError, OSError) as exc:
+            print(f"  ✗  {name}: {exc}", file=sys.stderr)
+            success = False
+
+    return success
+
+
+def _cmd_sync(args: list[str], toolkit_dir: Path) -> int:
+    """Sync skills to tool-specific directories."""
+    tools_arg: str | None = None
+    i = 0
+    while i < len(args):
+        if args[i] == "--tools" and i + 1 < len(args):
+            tools_arg = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    valid_tools = ("claude-code", "cursor", "opencode")
+    if tools_arg:
+        tools = [t.strip() for t in tools_arg.split(",") if t.strip()]
+    else:
+        # Default: all supported tools
+        tools = list(valid_tools)
+
+    print()
+    print("Syncing skills...")
+    print()
+
+    success = True
+    for tool in tools:
+        if tool == "claude-code":
+            print("── claude-code ──")
+            if not _sync_claude_code(toolkit_dir):
+                success = False
+            print()
+        elif tool == "cursor":
+            print("── cursor ──")
+            if not _sync_cursor(toolkit_dir):
+                success = False
+            print()
+        elif tool == "opencode":
+            print("── opencode ──")
+            if not _sync_opencode(toolkit_dir):
+                success = False
+            print()
+        else:
+            print(f"  ⚠  Unknown tool: {tool}  (valid: {', '.join(valid_tools)})")
+            success = False  # CLI-012 / #48 — unknown --tools must fail
+
+    return 0 if success else 1
+
+
+# ---------------------------------------------------------------------------
+# validate subcommand
+# ---------------------------------------------------------------------------
+
+
+def _validate_skill(skill_dir: Path, toolkit_dir: Path) -> tuple[int, int]:
+    """Validate a single skill directory. Returns (errors, warnings)."""
+    rel = skill_dir.relative_to(toolkit_dir)
+    skill_md = skill_dir / "SKILL.md"
+    errors = 0
+    warnings = 0
+
+    if not skill_md.exists():
+        print(f"  ✗  {rel}: missing SKILL.md")
+        return 1, 0
+
+    try:
+        content = skill_md.read_text(errors="replace")
+    except OSError as exc:
+        print(f"  ✗  {rel}/SKILL.md: cannot read: {exc}")
+        return 1, 0
+
+    fm = _parse_frontmatter_simple(content)
+    if fm is None:
+        print(f"  ✗  {rel}/SKILL.md: no YAML frontmatter found (must start with ---)")
+        return 1, 0
+
+    ok = True
+    for field in ("name", "description"):
+        if not fm.get(field):
+            print(f"  ✗  {rel}/SKILL.md: missing required frontmatter field '{field}'")
+            errors += 1
+            ok = False
+
+    if fm.get("name") and fm["name"] != skill_dir.name:
+        print(
+            f"  ⚠  {rel}/SKILL.md: name '{fm['name']}' does not match directory '{skill_dir.name}'"
+        )
+        warnings += 1
+
+    if (skill_dir / "skill.json").exists():
+        print(f"  ⚠  {rel}: skill.json found — not needed, can be removed")
+        warnings += 1
+
+    if ok:
+        print(f"  ✓  {rel}/SKILL.md")
+
+    return errors, warnings
+
+
+def _cmd_validate(toolkit_dir: Path) -> int:
+    """Validate SKILL.md frontmatter for all skills."""
+    skills_dir = toolkit_dir / "skills"
+    plugins_dir = toolkit_dir / "plugins"
+
+    if not skills_dir.is_dir():
+        print(f"  ✗  Skills directory not found: {skills_dir}", file=sys.stderr)
+        return 1
+
+    print()
+    print("Validating SKILL.md frontmatter...")
+    print()
+
+    total_errors = 0
+    total_warnings = 0
+    skill_count = 0
+
+    print("── skills/ ──")
+    for domain_dir in sorted(skills_dir.iterdir()):
+        if not domain_dir.is_dir():
+            continue
+        for skill_dir in sorted(domain_dir.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            errs, warns = _validate_skill(skill_dir, toolkit_dir)
+            total_errors += errs
+            total_warnings += warns
+            skill_count += 1
+
+    if plugins_dir.is_dir():
+        print()
+        print("── plugins/ (bundled copies) ──")
+        for plugin_dir in sorted(plugins_dir.iterdir()):
+            if not plugin_dir.is_dir():
+                continue
+            plugin_skills = plugin_dir / "skills"
+            if plugin_skills.exists():
+                for skill_dir in sorted(plugin_skills.iterdir()):
+                    if skill_dir.is_dir():
+                        errs, warns = _validate_skill(skill_dir, toolkit_dir)
+                        total_errors += errs
+                        total_warnings += warns
+
+    print()
+    print("── Summary ──")
+    print(f"  Skills validated: {skill_count}")
+
+    if total_errors:
+        print(f"\n  ✗  {total_errors} error(s) found")
+        return 1
+
+    if total_warnings:
+        print(f"\n  ⚠  All valid with {total_warnings} warning(s)")
+    else:
+        print("\n  ✓  All SKILL.md files are valid!")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing & dispatch
+# ---------------------------------------------------------------------------
+
+
+def cmd_skills(args: list[str]) -> int:
+    """Skill management entry point.
+
+    Returns 0 on success, 1 on failure.
+    """
+    if not args or args[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+
+    toolkit_dir = toolkit_root()
+    if toolkit_dir is None:
+        print("  ✗  Cannot locate toolkit directory", file=sys.stderr)
+        return 1
+
+    subcommand = args[0]
+    rest = args[1:]
+
+    if subcommand == "list":
+        return _cmd_list(rest, toolkit_dir)
+    elif subcommand == "sync":
+        return _cmd_sync(rest, toolkit_dir)
+    elif subcommand == "validate":
+        return _cmd_validate(toolkit_dir)
+    else:
+        print(f"  ✗  Unknown subcommand: {subcommand}", file=sys.stderr)
+        print("  Valid subcommands: list, sync, validate", file=sys.stderr)
+        return 1