devsync 0.5.5__py3-none-any.whl

aiconfigkit/cli/main.py

@@ -0,0 +1,454 @@
+"""Main CLI application entry point."""
+
+from typing import Optional
+
+import typer
+
+from aiconfigkit.cli.delete import delete_from_library
+from aiconfigkit.cli.download import download_instructions
+from aiconfigkit.cli.install_new import install_instruction_unified
+from aiconfigkit.cli.list import list_available, list_installed, list_library
+from aiconfigkit.cli.mcp_configure import mcp_configure_command
+from aiconfigkit.cli.mcp_install import mcp_install_command
+from aiconfigkit.cli.mcp_sync import mcp_sync_command
+from aiconfigkit.cli.package import package_app
+from aiconfigkit.cli.template import template_app
+from aiconfigkit.cli.template_backup import (
+    backup_cleanup_command,
+    backup_list_command,
+    backup_restore_command,
+)
+from aiconfigkit.cli.template_init import init_command as template_init_command
+from aiconfigkit.cli.template_install import install_command as template_install_command
+from aiconfigkit.cli.template_list import list_command as template_list_command
+from aiconfigkit.cli.template_uninstall import uninstall_command as template_uninstall_command
+from aiconfigkit.cli.template_update import update_command as template_update_command
+from aiconfigkit.cli.template_validate import validate_command as template_validate_command
+from aiconfigkit.cli.tools import show_tools
+from aiconfigkit.cli.uninstall import uninstall_instruction
+from aiconfigkit.cli.update import update_repository
+
+app = typer.Typer(
+    name="instructionkit",
+    help="CLI tool for managing AI coding tool instructions",
+    add_completion=False,
+)
+
+# Create list subcommand group
+list_app = typer.Typer(help="List instructions")
+app.add_typer(list_app, name="list")
+
+# Create package subcommand group
+app.add_typer(package_app, name="package")
+
+# Create template subcommand group
+app.add_typer(template_app, name="template")
+
+# Create backup subcommand group under template
+backup_app = typer.Typer(help="Manage template backups")
+template_app.add_typer(backup_app, name="backup")
+
+# Create mcp subcommand group
+mcp_app = typer.Typer(help="Manage MCP server configurations")
+app.add_typer(mcp_app, name="mcp")
+
+# Register mcp commands
+mcp_app.command(name="install")(mcp_install_command)
+mcp_app.command(name="configure")(mcp_configure_command)
+mcp_app.command(name="sync")(mcp_sync_command)
+
+# Register template commands
+template_app.command(name="init")(template_init_command)
+template_app.command(name="install")(template_install_command)
+template_app.command(name="list")(template_list_command)
+template_app.command(name="update")(template_update_command)
+template_app.command(name="uninstall")(template_uninstall_command)
+template_app.command(name="validate")(template_validate_command)
+
+# Register backup commands
+backup_app.command(name="list")(backup_list_command)
+backup_app.command(name="cleanup")(backup_cleanup_command)
+backup_app.command(name="restore")(backup_restore_command)
+
+
+@list_app.callback(invoke_without_command=True)
+def list_callback(ctx: typer.Context) -> None:
+    """List instructions (available, installed, or in library)."""
+    # If no subcommand was provided, show help
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+
+
+@app.command()
+def install(
+    names: Optional[list[str]] = typer.Argument(
+        None,
+        help="Instruction name(s) to install (use source/name for disambiguation). Can specify multiple.",
+    ),
+    source: Optional[str] = typer.Option(
+        None,
+        "--from",
+        "-f",
+        help="Source URL or path for direct install (bypasses library)",
+    ),
+    tools: Optional[list[str]] = typer.Option(
+        None,
+        "--tool",
+        "-t",
+        help="AI tool(s) to install to (cursor, copilot, windsurf, claude). Can specify multiple times.",
+    ),
+    conflict: str = typer.Option(
+        "prompt",
+        "--conflict",
+        "-c",
+        help="Conflict resolution strategy (prompt [default], skip, rename, overwrite)",
+    ),
+    bundle: bool = typer.Option(
+        False,
+        "--bundle",
+        "-b",
+        help="Install as bundle (multiple instructions)",
+    ),
+) -> None:
+    """
+    Install instructions from your library or directly from a source.
+
+    LIBRARY WORKFLOW (Recommended):
+      # Browse and select instructions with TUI
+      inskit install
+
+      # Install specific instruction from library
+      inskit install python-best-practices
+
+      # Install from specific source (if multiple sources have same name)
+      inskit install company/python-best-practices
+
+      # Install multiple instructions at once
+      inskit install python-style testing-guide api-design
+
+      # Install to specific tools only
+      inskit install python-style --tool cursor --tool windsurf
+
+    DIRECT INSTALL (Bypasses library):
+      # Install directly from source URL
+      inskit install python-style --from https://github.com/company/instructions
+
+      # Install bundle directly
+      inskit install python-backend --bundle --from https://github.com/company/instructions
+
+    TIP: Download to your library first for better management:
+      inskit download --from https://github.com/company/instructions
+    """
+    exit_code = install_instruction_unified(
+        names=names,
+        repo=source,  # Keep backend param name for now
+        tools=tools,
+        conflict_strategy=conflict,
+        bundle=bundle,
+    )
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def download(
+    source: str = typer.Option(
+        ...,
+        "--from",
+        "-f",
+        help="Source URL or local directory path",
+    ),
+    ref: Optional[str] = typer.Option(
+        None,
+        "--ref",
+        "-r",
+        help="Git reference (tag, branch, or commit) to download",
+    ),
+    alias: Optional[str] = typer.Option(
+        None,
+        "--as",
+        "-a",
+        help="Friendly alias for this source (auto-generated if not provided)",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Re-download even if already in library",
+    ),
+) -> None:
+    """
+    Download instructions from a source into your local library.
+
+    This downloads and caches instructions locally without installing them.
+    After downloading, use 'inskit install' to install instructions.
+
+    Examples:
+
+      # Download from GitHub (auto-generates alias)
+      inskit download --from github.com/company/instructions
+
+      # Download specific version
+      inskit download --from github.com/company/instructions --ref v1.0.0
+
+      # Download from branch
+      inskit download --from github.com/company/instructions --ref main
+
+      # Download with custom alias
+      inskit download --from github.com/company/instructions --as company
+
+      # Download from local folder
+      inskit download --from ./my-instructions --as local
+
+      # Force re-download
+      inskit download --from github.com/company/instructions --force
+    """
+    exit_code = download_instructions(repo=source, ref=ref, force=force, alias=alias)
+    raise typer.Exit(code=exit_code)
+
+
+@list_app.command("available")
+def list_available_cmd(
+    source: str = typer.Option(..., "--from", "-f", help="Source URL or local directory path"),
+    tag: Optional[str] = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+    bundles_only: bool = typer.Option(False, "--bundles-only", help="Show only bundles"),
+    instructions_only: bool = typer.Option(False, "--instructions-only", help="Show only instructions"),
+) -> None:
+    """
+    List available instructions from a source (without downloading).
+
+    Examples:
+
+      # List from Git repository
+      inskit list available --from github.com/company/instructions
+
+      # List from local folder
+      inskit list available --from ./my-instructions
+
+      # Filter by tag
+      inskit list available --from github.com/company/instructions --tag python
+
+      # Show only bundles
+      inskit list available --from github.com/company/instructions --bundles-only
+    """
+    exit_code = list_available(
+        repo=source,  # Keep backend param name for now
+        tag=tag,
+        bundles_only=bundles_only,
+        instructions_only=instructions_only,
+    )
+    raise typer.Exit(code=exit_code)
+
+
+@list_app.command("installed")
+def list_installed_cmd(
+    tool: Optional[str] = typer.Option(
+        None,
+        "--tool",
+        "-t",
+        help="Filter by AI tool (cursor, copilot, windsurf, claude)",
+    ),
+    source: Optional[str] = typer.Option(
+        None,
+        "--source",
+        "-s",
+        help="Filter by source alias or name",
+    ),
+) -> None:
+    """
+    List installed instructions in your AI tools.
+
+    Examples:
+
+      # List all installed instructions
+      inskit list installed
+
+      # Filter by AI tool
+      inskit list installed --tool cursor
+
+      # Filter by source
+      inskit list installed --source company
+    """
+    exit_code = list_installed(tool=tool, repo=source)  # Keep backend param name for now
+    raise typer.Exit(code=exit_code)
+
+
+@list_app.command("library")
+def list_library_cmd(
+    source: Optional[str] = typer.Option(
+        None,
+        "--source",
+        "-s",
+        help="Filter by source alias",
+    ),
+    instructions: bool = typer.Option(
+        False,
+        "--instructions",
+        "-i",
+        help="Show individual instructions instead of repositories",
+    ),
+) -> None:
+    """
+    List sources and instructions in your local library.
+
+    Examples:
+
+      # List all sources in library
+      inskit list library
+
+      # Show individual instructions
+      inskit list library --instructions
+
+      # Filter by source
+      inskit list library --source company
+    """
+    exit_code = list_library(repo_filter=source, show_instructions=instructions)
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def update(
+    namespace: Optional[str] = typer.Option(
+        None,
+        "--namespace",
+        "-n",
+        help="Repository namespace to update",
+    ),
+    all_repos: bool = typer.Option(
+        False,
+        "--all",
+        "-a",
+        help="Update all repositories in library",
+    ),
+) -> None:
+    """
+    Update downloaded instructions to their latest versions.
+
+    This re-downloads instructions from their sources,
+    ensuring you have the latest versions in your library.
+
+    Examples:
+
+      # Update a specific source
+      inskit update --namespace github.com_company_instructions
+
+      # Update all sources
+      inskit update --all
+
+      # List sources to find namespace
+      inskit list library
+    """
+    exit_code = update_repository(namespace=namespace, all_repos=all_repos)
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def delete(
+    namespace: str = typer.Argument(
+        ...,
+        help="Repository namespace to delete from library",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """
+    Delete a source from your local library.
+
+    This removes the downloaded instructions from your library but does NOT
+    uninstall them from your AI tools. To uninstall, use 'inskit uninstall'.
+
+    Examples:
+
+      # Delete a source
+      inskit delete github.com_company_instructions
+
+      # Skip confirmation
+      inskit delete github.com_company_instructions --force
+
+      # List sources to find namespace
+      inskit list library
+    """
+    exit_code = delete_from_library(namespace=namespace, force=force)
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def uninstall(
+    name: str = typer.Argument(..., help="Instruction name to uninstall"),
+    tool: Optional[str] = typer.Option(
+        None,
+        "--tool",
+        "-t",
+        help="AI tool to uninstall from (cursor, copilot, windsurf, claude)",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """
+    Uninstall an instruction from your AI tools.
+
+    Removes instructions from project level only.
+
+    Examples:
+
+      # Uninstall from all tools
+      inskit uninstall python-best-practices
+
+      # Uninstall from specific tool
+      inskit uninstall python-best-practices --tool cursor
+
+      # Skip confirmation
+      inskit uninstall python-best-practices --force
+    """
+    exit_code = uninstall_instruction(name=name, tool=tool, force=force)
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def tools() -> None:
+    """
+    Show detected AI coding tools.
+
+    Display which AI coding tools are installed on your system
+    and where their configuration directories are located.
+    """
+    exit_code = show_tools()
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def version() -> None:
+    """Show Config Sync version."""
+    from importlib.metadata import version as get_version
+
+    try:
+        version = get_version("configsync")
+    except Exception:
+        version = "unknown"
+
+    typer.echo(f"Config Sync version {version}")
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """
+    InstructionKit - Manage AI coding tool instructions from Git repositories.
+
+    Install instructions for Cursor, GitHub Copilot, Windsurf, and Claude Code
+    from any Git repository (public or private).
+    """
+    # If no command was provided, show help
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+
+
+if __name__ == "__main__":
+    app()

aiconfigkit/cli/mcp_configure.py

@@ -0,0 +1,232 @@
+"""CLI command for configuring MCP server credentials."""
+
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from aiconfigkit.core.mcp.credentials import CredentialManager
+from aiconfigkit.core.mcp.manager import MCPManager
+from aiconfigkit.core.models import InstallationScope
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+def mcp_configure_command(
+    server_ref: str = typer.Argument(..., help="Server reference in format 'namespace.server' or just 'namespace'"),
+    scope: str = typer.Option("project", "--scope", help="Installation scope: project or global"),
+    non_interactive: bool = typer.Option(False, "--non-interactive", help="Read credentials from environment"),
+    show_current: bool = typer.Option(False, "--show-current", help="Show current credential values (masked)"),
+    json_output: bool = typer.Option(False, "--json", help="Output results as JSON"),
+) -> int:
+    """
+    Configure credentials for MCP servers.
+
+    This command helps you securely configure required environment variables for
+    MCP servers. Credentials are stored in .instructionkit/.env (gitignored).
+
+    Examples:
+
+        # Configure specific server interactively
+        inskit mcp configure backend.github
+
+        # Configure all servers in a namespace
+        inskit mcp configure backend
+
+        # Configure with non-interactive mode (read from env)
+        export GITHUB_TOKEN=ghp_xxxxx
+        inskit mcp configure backend.github --non-interactive
+
+        # Show current credentials (masked)
+        inskit mcp configure backend.github --show-current
+
+        # Configure globally (available in all projects)
+        inskit mcp configure backend.github --scope global
+    """
+    try:
+        # Parse scope
+        try:
+            install_scope = InstallationScope(scope)
+        except ValueError:
+            console.print(f"[red]Error:[/red] Invalid scope '{scope}'. Must be 'project' or 'global'")
+            return 1
+
+        # Parse server reference
+        if "." in server_ref:
+            namespace, server_name = server_ref.rsplit(".", 1)
+        else:
+            namespace = server_ref
+            server_name = None
+
+        # Get library root and managers
+        library_root = _get_library_root()
+        mcp_manager = MCPManager(library_root)
+        cred_manager = CredentialManager()
+
+        # Load template
+        template = mcp_manager.load_template(namespace, scope=install_scope)
+
+        if not template:
+            console.print(f"[red]Error:[/red] Template '{namespace}' not found in {install_scope.value} scope")
+            console.print(f"\nInstall it first: [cyan]inskit mcp install <source> --as {namespace}[/cyan]")
+            return 1
+
+        # Get servers to configure
+        if server_name:
+            # Configure specific server
+            server = template.get_server_by_name(server_name)
+            if not server:
+                console.print(f"[red]Error:[/red] Server '{server_name}' not found in template '{namespace}'")
+                console.print(f"\nAvailable servers: {', '.join(s.name for s in template.servers)}")
+                return 1
+            servers = [server]
+        else:
+            # Configure all servers in namespace
+            servers = template.servers
+
+        if not servers:
+            console.print(f"[yellow]Warning:[/yellow] No MCP servers found in template '{namespace}'")
+            return 0
+
+        # Show current credentials if requested
+        if show_current:
+            return _show_current_credentials(servers, cred_manager, install_scope, json_output)
+
+        # Configure each server
+        configured_count = 0
+        skipped_count = 0
+
+        for server in servers:
+            required_vars = server.get_required_env_vars()
+
+            if not required_vars:
+                console.print(f"[dim]Server '{server.name}' requires no credentials[/dim]")
+                skipped_count += 1
+                continue
+
+            try:
+                cred_manager.configure_server(
+                    server,
+                    scope=install_scope,
+                    non_interactive=non_interactive,
+                )
+                configured_count += 1
+
+            except ValueError as e:
+                console.print(f"[red]Error configuring '{server.name}':[/red] {e}")
+                return 1
+
+        # Output results
+        if json_output:
+            import json
+
+            result = {
+                "success": True,
+                "namespace": namespace,
+                "configured": configured_count,
+                "skipped": skipped_count,
+                "total": len(servers),
+                "scope": install_scope.value,
+            }
+            console.print(json.dumps(result, indent=2))
+        else:
+            console.print("\n[green]✓[/green] Credential configuration complete!")
+            console.print(f"  Configured: {configured_count} server(s)")
+            if skipped_count > 0:
+                console.print(f"  Skipped: {skipped_count} server(s) (no credentials needed)")
+
+            # Show env file location
+            if install_scope == InstallationScope.GLOBAL:
+                env_path = Path.home() / ".instructionkit" / "global" / ".env"
+            else:
+                env_path = Path.cwd() / ".instructionkit" / ".env"
+
+            console.print(f"\n[dim]Credentials saved to: {env_path}[/dim]")
+            console.print("[dim](This file is automatically gitignored)[/dim]")
+
+            # Show next steps
+            console.print("\n[bold]Next step:[/bold]")
+            console.print("  Sync to AI tools: [cyan]inskit mcp sync --tool all[/cyan]")
+
+        return 0
+
+    except Exception as e:
+        logger.exception("Unexpected error during credential configuration")
+        if json_output:
+            import json
+
+            console.print(json.dumps({"success": False, "error": str(e)}, indent=2))
+        else:
+            console.print(f"[red]Unexpected error:[/red] {e}")
+        return 1
+
+
+def _show_current_credentials(
+    servers: list,
+    cred_manager: CredentialManager,
+    scope: InstallationScope,
+    json_output: bool,
+) -> int:
+    """Show current credential values for servers."""
+    if json_output:
+        import json
+        from typing import Any
+
+        result: dict[str, Any] = {
+            "scope": scope.value,
+            "servers": [],
+        }
+
+        for server in servers:
+            credentials = cred_manager.show_current_credentials(server, scope)
+            is_valid, missing = cred_manager.validate_credentials(server, scope)
+
+            result["servers"].append(
+                {
+                    "name": server.get_fully_qualified_name(),
+                    "credentials": credentials,
+                    "is_configured": is_valid,
+                    "missing": missing,
+                }
+            )
+
+        console.print(json.dumps(result, indent=2))
+    else:
+        table = Table(title=f"Current Credentials ({scope.value} scope)")
+        table.add_column("Server", style="cyan")
+        table.add_column("Variable", style="yellow")
+        table.add_column("Value", style="dim")
+        table.add_column("Status", style="green")
+
+        for server in servers:
+            credentials = cred_manager.show_current_credentials(server, scope)
+            is_valid, missing = cred_manager.validate_credentials(server, scope)
+
+            for i, (var_name, masked_value) in enumerate(credentials.items()):
+                server_name = server.get_fully_qualified_name() if i == 0 else ""
+                status = "✓" if var_name not in missing else "⚠ Missing"
+                status_style = "green" if var_name not in missing else "yellow"
+
+                table.add_row(
+                    server_name,
+                    var_name,
+                    masked_value,
+                    f"[{status_style}]{status}[/{status_style}]",
+                )
+
+        console.print(table)
+
+    return 0
+
+
+def _get_library_root() -> Path:
+    """
+    Get the library root directory.
+
+    Returns:
+        Path to library root (~/.instructionkit/library/)
+    """
+    return Path.home() / ".instructionkit" / "library"