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

agent_toolkit/cli/main.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""agent-toolkit CLI entrypoint — see docs/CLI_SURFACES.md."""
+
+from __future__ import annotations
+
+import sys
+
+CONSUMER_COMMANDS: tuple[str, ...] = (
+    "install",
+    "update",
+    "uninstall",
+    "doctor",
+    "diff",
+    "skills",
+    "mcp",
+    "plugin",
+)
+ADVANCED_COMMANDS: tuple[str, ...] = (
+    "loop",
+    "workspace",
+    "memory",
+    "project",
+    "devcompanion",
+    "dc",
+    "insights",
+    "build",
+    "inventory",
+    "matrix",
+    "release",
+    "swarm",
+)
+
+_CONSUMER_HELP = """\
+agent-toolkit — Composable AI agent toolkit CLI
+
+Usage:
+    agent-toolkit <command> [args...]
+
+Consumer commands:
+    install       Install profiles for detected AI tools
+    update        Refresh installed profiles from latest toolkit data
+    uninstall     Remove toolkit-owned files using install receipts
+    doctor        Check system health and tool availability
+    diff          Show changes vs currently installed plugin bundles
+    skills        Skill management: sync, list, validate
+    mcp           MCP provider management: setup, list, doctor
+    plugin        Plugin bundle management: sync, check
+
+Advanced commands (workstation / power-user — docs/CLI_SURFACES.md):
+    loop          Loop engineering: init, run, status, audit, cost, schedule, sync
+    workspace     Workspace scaffolding: init, context, sync
+    memory        Knowledge base: add, search, inject, review, todo
+    project       Project management: clone, list, add, remove, scan
+    devcompanion  Background job queue: queue, run-once, status, done, sync-todos
+    insights      AI tool usage insights: opencode, cursor, claude
+    build         Compile canonical capabilities into target-native artifacts
+    inventory     List all canonical skills, agents, and products
+    matrix        Show platform capability matrix
+    release       Generate release artifacts (maintainer)
+    swarm         Multi-agent swarm orchestration (pair/team/full, Herdr/tmux)
+
+Run 'agent-toolkit <command> --help' for details.
+"""
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(_CONSUMER_HELP)
+        sys.exit(0)
+
+    if argv[0] in ("-V", "--version", "version"):
+        from agent_toolkit import __version__
+
+        print(f"agent-toolkit {__version__}")
+        sys.exit(0)
+
+    command = argv[0]
+    rest = argv[1:]
+
+    match command:
+        case "release":
+            from agent_toolkit.cli.release import cmd_release
+
+            sys.exit(cmd_release(rest))
+        case "diff":
+            from agent_toolkit.cli.diff import cmd_diff
+
+            sys.exit(cmd_diff(rest))
+        case "build":
+            from agent_toolkit.cli.build import cmd_build
+
+            sys.exit(cmd_build(rest))
+        case "inventory":
+            from agent_toolkit.cli.build import cmd_inventory
+
+            sys.exit(cmd_inventory(rest))
+        case "matrix":
+            from agent_toolkit.cli.build import cmd_matrix
+
+            sys.exit(cmd_matrix(rest))
+        case "install":
+            from agent_toolkit.cli.install import cmd_install
+
+            sys.exit(cmd_install(rest))
+        case "update":
+            from agent_toolkit.cli.update import cmd_update
+
+            sys.exit(cmd_update(rest))
+        case "uninstall" | "rollback":
+            from agent_toolkit.cli.uninstall import cmd_uninstall
+
+            sys.exit(cmd_uninstall(rest))
+        case "doctor":
+            from agent_toolkit.cli.doctor import cmd_doctor
+
+            sys.exit(cmd_doctor(rest))
+        case "loop":
+            from agent_toolkit.loop import runner
+
+            sys.argv = ["agent-toolkit loop"] + rest
+            runner.main()
+        case "mcp":
+            from agent_toolkit.cli.mcp import cmd_mcp
+
+            sys.exit(cmd_mcp(rest))
+        case "skills":
+            from agent_toolkit.cli.skills import cmd_skills
+
+            sys.exit(cmd_skills(rest))
+        case "plugin":
+            from agent_toolkit.cli.plugin import cmd_plugin
+
+            sys.exit(cmd_plugin(rest))
+        case "workspace":
+            from agent_toolkit.cli.workspace import cmd_workspace
+
+            sys.exit(cmd_workspace(rest))
+        case "memory":
+            from agent_toolkit.cli.memory import cmd_memory
+
+            sys.exit(cmd_memory(rest))
+        case "project":
+            from agent_toolkit.cli.project import cmd_project
+
+            sys.exit(cmd_project(rest))
+        case "devcompanion" | "dc":
+            from agent_toolkit.cli.devcompanion import cmd_devcompanion
+
+            sys.exit(cmd_devcompanion(rest))
+        case "insights":
+            from agent_toolkit.cli.insights import cmd_insights
+
+            sys.exit(cmd_insights(rest))
+        case "swarm":
+            from agent_toolkit.swarm.cli import main as swarm_main
+
+            sys.exit(swarm_main(rest))
+        case _:
+            print(f"Unknown command: {command}", file=sys.stderr)
+            print("Run 'agent-toolkit help' for usage.", file=sys.stderr)
+            if command not in CONSUMER_COMMANDS and command not in ADVANCED_COMMANDS:
+                print(
+                    "See docs/CLI_SURFACES.md for consumer vs advanced commands.",
+                    file=sys.stderr,
+                )
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

agent_toolkit/cli/mcp.py

@@ -0,0 +1,537 @@
+"""
+mcp — MCP (Model Context Protocol) provider management.
+
+Usage:
+    agent-toolkit mcp <subcommand> [args]
+
+Subcommands:
+    list                   List available MCP providers
+    setup <provider>       Interactive wizard to configure a provider
+    health [provider]      Validate registry entry and required env var names (no network)
+    doctor [provider]      Check env vars and connectivity for provider(s)
+    uninstall <provider>   Remove a provider from local MCP config
+
+Options:
+    --offline              Skip network connectivity checks (setup/doctor)
+    --help                 Show this help message
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agent_toolkit._paths import toolkit_root
+
+# ---------------------------------------------------------------------------
+# Toolkit directory & config paths
+# ---------------------------------------------------------------------------
+
+
+def _mcp_config_path() -> Path:
+    return Path.home() / ".config" / "agent-toolkit" / "mcp-config.json"
+
+
+def _templates_dir(toolkit_dir: Path) -> Path:
+    return toolkit_dir / "mcp" / "templates"
+
+
+def _registry_dir(toolkit_dir: Path) -> Path:
+    return toolkit_dir / "mcp" / "registry"
+
+
+def _load_registry_provider(toolkit_dir: Path, provider: str):
+    """Load provider metadata from mcp/registry/<provider>.yaml."""
+    from agent_toolkit.compiler.mcp_registry import load_registry
+
+    registry, _errors = load_registry(_registry_dir(toolkit_dir))
+    return registry.get(provider)
+
+
+def _registry_env_vars(toolkit_dir: Path, provider: str) -> list[str]:
+    entry = _load_registry_provider(toolkit_dir, provider)
+    if entry is None:
+        template = _load_template(_templates_dir(toolkit_dir), provider)
+        return _extract_env_vars(template) if template else []
+    return list(entry.env_vars)
+
+
+def _list_known_providers(toolkit_dir: Path) -> list[str]:
+    reg_dir = _registry_dir(toolkit_dir)
+    names = {p.stem for p in reg_dir.glob("*.yaml")} if reg_dir.is_dir() else set()
+    tdir = _templates_dir(toolkit_dir)
+    if tdir.is_dir():
+        names.update(p.name for p in tdir.iterdir() if p.is_dir())
+    return sorted(names)
+
+
+# ---------------------------------------------------------------------------
+# Config I/O
+# ---------------------------------------------------------------------------
+
+
+def _load_config() -> dict:
+    path = _mcp_config_path()
+    if not path.exists():
+        return {"providers": {}}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {"providers": {}}
+
+
+def _save_config(cfg: dict) -> None:
+    path = _mcp_config_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(cfg, indent=2) + "\n")
+    except (PermissionError, OSError) as exc:
+        print(f"  ✗  Failed to save config: {exc}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Template parsing
+# ---------------------------------------------------------------------------
+
+
+def _extract_env_vars(template: dict) -> list[str]:
+    """Extract ${ENV_VAR} names from all string values in a dict (recursive)."""
+    pattern = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+    found: list[str] = []
+
+    def _walk(obj: object) -> None:
+        if isinstance(obj, str):
+            for m in pattern.finditer(obj):
+                name = m.group(1)
+                if name not in found:
+                    found.append(name)
+        elif isinstance(obj, dict):
+            for v in obj.values():
+                _walk(v)
+        elif isinstance(obj, list):
+            for item in obj:
+                _walk(item)
+
+    _walk(template)
+    return found
+
+
+def _load_template(templates_dir: Path, provider: str) -> dict | None:
+    """Load and parse a provider's config.template.json."""
+    template_file = templates_dir / provider / "config.template.json"
+    if not template_file.exists():
+        return None
+    try:
+        return json.loads(template_file.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"  ✗  Cannot read template {template_file}: {exc}", file=sys.stderr)
+        return None
+
+
+def _load_readme(templates_dir: Path, provider: str) -> str:
+    readme = templates_dir / provider / "README.md"
+    if readme.exists():
+        try:
+            return readme.read_text().strip()
+        except OSError:
+            pass
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Connectivity tests
+# ---------------------------------------------------------------------------
+
+
+def _test_github(token: str) -> tuple[bool, str]:
+    try:
+        req = urllib.request.Request("https://api.github.com/user")
+        req.add_header("Authorization", f"Bearer {token}")
+        req.add_header("User-Agent", "agent-toolkit-mcp/1")
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            data = json.loads(resp.read())
+            return True, f"Authenticated as: {data.get('login', 'unknown')}"
+    except urllib.error.HTTPError as exc:
+        return False, f"HTTP {exc.code}: {exc.reason}"
+    except Exception as exc:
+        return False, str(exc)
+
+
+def _test_connectivity(provider: str, env_vals: dict[str, str]) -> tuple[bool, str]:
+    """Run a lightweight connectivity test if we know how for this provider."""
+    if provider == "github":
+        token = env_vals.get("GITHUB_TOKEN", "")
+        if token:
+            return _test_github(token)
+        return False, "GITHUB_TOKEN not provided"
+    # For other providers we just confirm env vars are set
+    return True, "env vars provided (connectivity test not available for this provider)"
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+
+def _cmd_list(toolkit_dir: Path | None) -> int:
+    """List available MCP providers from mcp/templates/."""
+    if toolkit_dir is None:
+        print("  ✗  Cannot locate toolkit directory", file=sys.stderr)
+        return 1
+
+    tdir = _templates_dir(toolkit_dir)
+    if not tdir.is_dir():
+        print(f"  ✗  MCP templates directory not found: {tdir}", file=sys.stderr)
+        return 1
+
+    providers = sorted(p.name for p in tdir.iterdir() if p.is_dir())
+    if not providers:
+        print("  ⚠  No MCP provider templates found")
+        return 0
+
+    cfg = _load_config()
+    configured = cfg.get("providers", {})
+
+    print()
+    print("Available MCP providers")
+    print()
+    col_name = max(len(p) for p in providers) + 2
+
+    header = f"  {'Provider':<{col_name}}  {'Status':<12}  Required env vars"
+    print(header)
+    print("  " + "-" * (len(header) - 2))
+
+    for provider in providers:
+        template = _load_template(tdir, provider)
+        env_vars = _extract_env_vars(template) if template else []
+        env_str = ", ".join(env_vars) if env_vars else "(none)"
+
+        prov_cfg = configured.get(provider, {})
+        if prov_cfg.get("enabled"):
+            status = "✓ configured"
+        elif prov_cfg:
+            status = "- disabled"
+        else:
+            status = "  not setup"
+
+        print(f"  {provider:<{col_name}}  {status:<12}  {env_str}")
+
+    print()
+    print("Run: agent-toolkit mcp setup <provider>")
+    print()
+    return 0
+
+
+def _cmd_setup(provider: str, toolkit_dir: Path | None, *, offline: bool = False) -> int:
+    """Interactive wizard to configure an MCP provider."""
+    if toolkit_dir is None:
+        print("  ✗  Cannot locate toolkit directory", file=sys.stderr)
+        return 1
+
+    tdir = _templates_dir(toolkit_dir)
+    template = _load_template(tdir, provider)
+    entry = _load_registry_provider(toolkit_dir, provider)
+    if entry is None and template is None:
+        providers = _list_known_providers(toolkit_dir)
+        print(f"  ✗  Provider '{provider}' not found.", file=sys.stderr)
+        if providers:
+            print(f"  Available: {', '.join(providers)}", file=sys.stderr)
+        return 1
+
+    env_vars = _registry_env_vars(toolkit_dir, provider)
+    if not env_vars and template is not None:
+        env_vars = _extract_env_vars(template)
+    readme = _load_readme(tdir, provider)
+
+    print()
+    print(f"MCP setup: {provider}")
+    print()
+
+    if readme:
+        # Print the first paragraph of the README as a hint
+        first_para = readme.split("\n\n")[0]
+        for line in first_para.splitlines():
+            print(f"  {line}")
+        print()
+
+    if not env_vars:
+        print("  ⚠  No environment variables required for this provider.")
+    else:
+        print(f"  Required env vars: {', '.join(env_vars)}")
+        print()
+
+    # Collect env var values
+    import getpass
+
+    env_vals: dict[str, str] = {}
+    token_words = ("TOKEN", "KEY", "SECRET", "PASSWORD", "PASS")
+
+    for var in env_vars:
+        current = os.environ.get(var, "")
+        is_sensitive = any(w in var.upper() for w in token_words)
+
+        if current:
+            hint = "[already set in env"
+            if is_sensitive:
+                hint += ", press Enter to keep]"
+            else:
+                hint += f" = {current!r}, press Enter to keep]"
+        else:
+            hint = "[required]"
+
+        prompt = f"  {var} {hint}: "
+
+        try:
+            if is_sensitive:
+                value = getpass.getpass(prompt) or current
+            else:
+                value = input(prompt).strip() or current
+        except (EOFError, KeyboardInterrupt):
+            print()
+            print("  ⚠  Setup cancelled")
+            return 1
+
+        env_vals[var] = value
+
+    # Validate / test connectivity
+    print()
+    if offline:
+        print("  ✓  Offline mode — skipping connectivity check")
+        ok, detail = True, "registry and env var names validated"
+    else:
+        print("  Testing connectivity...")
+        ok, detail = _test_connectivity(provider, env_vals)
+    if ok:
+        print(f"  ✓  {detail}")
+    else:
+        print(f"  ⚠  Connectivity check failed: {detail}")
+        if not offline:
+            print("     Saving configuration anyway — double-check your credentials.")
+
+    # Save config: store env var names (not plaintext values)
+    cfg = _load_config()
+    cfg.setdefault("providers", {})[provider] = {
+        "enabled": True,
+        "required_env": env_vars,
+        "validated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    _save_config(cfg)
+    print(f"  ✓  Saved to {_mcp_config_path()}")
+    print()
+
+    # Next steps per tool
+    print("── Next steps ──")
+    print()
+    print("  Export env vars in your shell profile (e.g. ~/.zshrc / ~/.bashrc):")
+    print()
+    for var in env_vars:
+        print(f'    export {var}="<your-value>"')
+    print()
+    print("  Then configure each AI tool:")
+    print("    Claude Code  → add MCP server to ~/.claude/settings.json")
+    print("    Cursor       → add MCP server in Cursor Settings → MCP")
+    print("    OpenCode     → add entry to ~/.config/opencode/opencode.json")
+    print()
+    print(f"  See: mcp/templates/{provider}/README.md for full instructions")
+    print()
+    return 0
+
+
+def _cmd_doctor_provider(provider: str, toolkit_dir: Path | None) -> tuple[int, int, int]:
+    """Check a single provider. Returns (ok, warn, err) counts."""
+    n_ok = n_warn = n_err = 0
+
+    if toolkit_dir:
+        tdir = _templates_dir(toolkit_dir)
+        template = _load_template(tdir, provider)
+        env_vars = _extract_env_vars(template) if template else []
+    else:
+        env_vars = []
+
+    cfg = _load_config()
+    prov_cfg = cfg.get("providers", {}).get(provider, {})
+    if not prov_cfg:
+        print(f"  ⚠  {provider}: not configured (run: agent-toolkit mcp setup {provider})")
+        n_warn += 1
+    else:
+        enabled = prov_cfg.get("enabled", False)
+        validated = prov_cfg.get("validated_at", "never")
+        icon = "✓" if enabled else "⚠"
+        print(f"  {icon}  {provider}: enabled={enabled}, validated_at={validated}")
+        if enabled:
+            n_ok += 1
+        else:
+            n_warn += 1
+
+    # Check env vars
+    for var in env_vars:
+        if os.environ.get(var):
+            print(f"  ✓  {var}: set")
+            n_ok += 1
+        else:
+            print(f"  ✗  {var}: not set in environment")
+            n_err += 1
+
+    # Connectivity test
+    env_vals = {v: os.environ.get(v, "") for v in env_vars}
+    if all(env_vals.values()):
+        ok, detail = _test_connectivity(provider, env_vals)
+        if ok:
+            print(f"  ✓  connectivity: {detail}")
+            n_ok += 1
+        else:
+            print(f"  ⚠  connectivity: {detail}")
+            n_warn += 1
+
+    return n_ok, n_warn, n_err
+
+
+def _cmd_doctor(providers_arg: list[str], toolkit_dir: Path | None) -> int:
+    """Check MCP provider configuration and connectivity."""
+    cfg = _load_config()
+    configured_providers = list(cfg.get("providers", {}).keys())
+
+    if providers_arg:
+        targets = providers_arg
+    elif configured_providers:
+        targets = configured_providers
+    else:
+        print("  ⚠  No MCP providers configured. Run: agent-toolkit mcp list")
+        return 0
+
+    print()
+    print("MCP doctor")
+
+    total_ok = total_warn = total_err = 0
+    for provider in targets:
+        print(f"\n── {provider} ──")
+        n_ok, n_warn, n_err = _cmd_doctor_provider(provider, toolkit_dir)
+        total_ok += n_ok
+        total_warn += n_warn
+        total_err += n_err
+
+    print()
+    print(f"── Summary: {total_ok} ok, {total_warn} warnings, {total_err} errors ──")
+    print()
+    return 1 if total_err else 0
+
+
+def _cmd_health(providers_arg: list[str], toolkit_dir: Path | None) -> int:
+    """Validate registry metadata and env var names without network calls."""
+    if toolkit_dir is None:
+        print("  ✗  Cannot locate toolkit directory", file=sys.stderr)
+        return 1
+
+    targets = providers_arg or _list_known_providers(toolkit_dir)
+    if not targets:
+        print("  ⚠  No MCP providers found in registry or templates")
+        return 0
+
+    print()
+    print("MCP health (offline)")
+    errors = 0
+    for provider in targets:
+        print(f"\n── {provider} ──")
+        entry = _load_registry_provider(toolkit_dir, provider)
+        if entry is None:
+            print("  ✗  Not in mcp/registry/ and no template directory")
+            errors += 1
+            continue
+        print(f"  ✓  registry: {entry.display_name} ({entry.id})")
+        if entry.package:
+            print(f"  ✓  package: {entry.package}")
+        env_vars = entry.env_vars
+        if env_vars:
+            print(f"  ✓  required env: {', '.join(env_vars)}")
+            for var in env_vars:
+                if os.environ.get(var):
+                    print(f"  ✓  {var}: set")
+                else:
+                    print(f"  -  {var}: not set (expected until configured)")
+        else:
+            print("  ✓  required env: (none)")
+
+    print()
+    return 1 if errors else 0
+
+
+def _cmd_uninstall(provider: str) -> int:
+    """Remove a provider from the local MCP config file."""
+    cfg = _load_config()
+    providers = cfg.get("providers", {})
+    if provider not in providers:
+        print(f"  ⚠  Provider '{provider}' is not configured")
+        return 0
+    del providers[provider]
+    cfg["providers"] = providers
+    _save_config(cfg)
+    print(f"  ✓  Removed '{provider}' from {_mcp_config_path()}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing & dispatch
+# ---------------------------------------------------------------------------
+
+
+def _pop_offline_flag(args: list[str]) -> tuple[list[str], bool]:
+    rest: list[str] = []
+    offline = False
+    for arg in args:
+        if arg == "--offline":
+            offline = True
+        else:
+            rest.append(arg)
+    return rest, offline
+
+
+def cmd_mcp(args: list[str]) -> int:
+    """MCP provider 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()
+    rest, offline = _pop_offline_flag(args)
+    if not rest or rest[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+
+    subcommand = rest[0]
+    subargs = rest[1:]
+
+    if subcommand == "list":
+        return _cmd_list(toolkit_dir)
+
+    elif subcommand == "setup":
+        if not subargs:
+            print("  ✗  Usage: agent-toolkit mcp setup <provider>", file=sys.stderr)
+            return 1
+        return _cmd_setup(subargs[0], toolkit_dir, offline=offline)
+
+    elif subcommand == "health":
+        return _cmd_health(subargs, toolkit_dir)
+
+    elif subcommand == "doctor":
+        if offline:
+            return _cmd_health(subargs, toolkit_dir)
+        return _cmd_doctor(subargs, toolkit_dir)
+
+    elif subcommand == "uninstall":
+        if not subargs:
+            print("  ✗  Usage: agent-toolkit mcp uninstall <provider>", file=sys.stderr)
+            return 1
+        return _cmd_uninstall(subargs[0])
+
+    else:
+        print(f"  ✗  Unknown subcommand: {subcommand}", file=sys.stderr)
+        print("  Valid subcommands: list, setup, health, doctor, uninstall", file=sys.stderr)
+        return 1