@ngocsangairvds/vsaf 4.1.9 → 4.1.11

package/skills/vds-skill/runtime/sonarqube_orchestrator/src/vds_sonarqube_orchestrator/cli.py

@@ -0,0 +1,1407 @@
+"""CLI for VDS SonarQube Orchestrator.
+
+Provides command-line access to SonarQube code quality scanning and issue management.
+
+Usage:
+    # Via direct script
+    uv run vds-sonarqube ping
+    uv run vds-sonarqube projects list
+    uv run vds-sonarqube issues list --project ekyc-business
+
+    # Via vds-cli router
+    ./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube -- ping
+    ./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube -- projects list
+    ./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube -- issues list --project ekyc-business
+
+    # JSON-only mode (clean JSON output, no headers/decoration)
+    uv run vds-sonarqube --json ping
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+if TYPE_CHECKING:
+    from vds_sonarqube_orchestrator.external_sca import ExternalSCAClient
+from vds_cli_common.app import make_vds_app
+from vds_cli_common.context import CLIContext
+from vds_cli_common.output import OutputManager
+from vds_cli_common.paths import get_shared_env_path
+from vds_platform_core.logging import configure_structlog
+
+from vds_sonarqube_orchestrator.client import SonarqubeClient
+from vds_sonarqube_orchestrator.config import SettingsError, load_settings
+from vds_sonarqube_orchestrator.errors import (
+    AuthError,
+    ClientPermissionError,
+    NotFoundError,
+    VDSClientError,
+)
+
+configure_structlog()
+app = make_vds_app(
+    name="vds-sonarqube",
+    help="VDS SonarQube CLI - Code quality scanning and issue management",
+    settings_factory=load_settings,
+)
+
+
+# -----------------------------------------------------------------------------
+# Helper Functions
+# -----------------------------------------------------------------------------
+
+
+def _get_client() -> SonarqubeClient:
+    """Load settings and create client."""
+    settings = load_settings(strict=True)
+    return SonarqubeClient(settings)
+
+
+def _handle_error(exc: VDSClientError, out: OutputManager) -> None:
+    """Handle SonarQube client errors with appropriate hints."""
+    if isinstance(exc, AuthError):
+        out.output_error(
+            str(exc),
+            hint="Check VDS_SONAR_TOKEN or VDS_SONAR_USER/VDS_SONAR_PASSWORD",
+        )
+    elif isinstance(exc, ClientPermissionError):
+        out.output_error(
+            str(exc),
+            hint="Ensure your SonarQube user has access to the requested resource",
+        )
+    elif isinstance(exc, NotFoundError):
+        out.output_error(
+            str(exc),
+            hint="Check the project key or resource identifier",
+        )
+    else:
+        out.output_error(
+            str(exc),
+            hint="Ensure Maven or sonar-scanner is installed and in PATH",
+        )
+
+
+def _get_sca_client() -> ExternalSCAClient:
+    """Load settings and create SCA client."""
+    from vds_sonarqube_orchestrator.external_sca import ExternalSCAClient
+
+    settings = load_settings()
+    return ExternalSCAClient(settings)
+
+
+# -----------------------------------------------------------------------------
+# Health Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command()
+def ping(
+    ctx: typer.Context,
+) -> None:
+    """Test connectivity to SonarQube server.
+
+    Verifies that:
+    1. SonarQube server is reachable
+    2. Authentication works
+    """
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            result = client.ping()
+            status = str(result.get("status", "UNKNOWN"))
+            is_up = status.upper() == "UP"
+            out.output_json(result)
+            raise typer.Exit(0 if is_up else 1)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Project Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("projects")
+def projects_cmd(
+    ctx: typer.Context,
+    query: Annotated[
+        str | None,
+        typer.Option("--query", "-q", help="Filter projects by name"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum results"),
+    ] = 100,
+) -> None:
+    """List all accessible SonarQube projects."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            result = client.search_projects(query=query, per_page=limit)
+            out.output_json(result)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+@app.command("project")
+def project_get(
+    ctx: typer.Context,
+    key: Annotated[
+        str,
+        typer.Option("--key", "-k", help="Project key"),
+    ],
+) -> None:
+    """Get details for a specific project."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            result = client.get_project(key)
+            out.output_json(result)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Issue Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("issues")
+def issues_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Project key"),
+    ] = None,
+    severities: Annotated[
+        str | None,
+        typer.Option(
+            "--severities",
+            "-s",
+            help="Comma-separated severities (BLOCKER,CRITICAL,MAJOR,MINOR,INFO)",
+        ),
+    ] = None,
+    types: Annotated[
+        str | None,
+        typer.Option(
+            "--types",
+            "-t",
+            help="Comma-separated types (BUG,VULNERABILITY,CODE_SMELL)",
+        ),
+    ] = None,
+    statuses: Annotated[
+        str | None,
+        typer.Option(
+            "--statuses",
+            help="Comma-separated statuses (OPEN,CONFIRMED,REOPENED,RESOLVED,CLOSED)",
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum results"),
+    ] = 100,
+) -> None:
+    """List issues for a project."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            sev_list = severities.split(",") if severities else None
+            type_list = types.split(",") if types else None
+            status_list = statuses.split(",") if statuses else None
+
+            result = client.get_issues(
+                project_key=project,
+                severities=sev_list,
+                types=type_list,
+                statuses=status_list,
+                per_page=limit,
+            )
+            out.output_json(result)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Metrics/Measures Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("measures")
+def measures_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Project key"),
+    ] = None,
+    metrics: Annotated[
+        str,
+        typer.Option(
+            "--metrics",
+            "-m",
+            help='Comma-separated metric keys (default: "bugs,vulnerabilities,coverage")',
+        ),
+    ] = "bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density",
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+) -> None:
+    """Get quality metrics for a project."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            metric_list = metrics.split(",")
+            result = client.get_measures(project, metric_list, branch)
+            out.output_json(result)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Quality Gate Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("qualitygate")
+def qualitygate_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Project key"),
+    ] = None,
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+) -> None:
+    """Check quality gate status for a project."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        with _get_client() as client:
+            result = client.get_quality_gate_status(project, branch)
+            project_status = result.get("projectStatus", {})
+            status = project_status.get("status", "UNKNOWN")
+            out.output_json(result)
+            raise typer.Exit(0 if status == "OK" else 1)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Scan Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("scan")
+def scan_cmd(
+    ctx: typer.Context,
+    scan_type: Annotated[
+        str,
+        typer.Option("--type", "-t", help="Scan type: maven or scanner"),
+    ] = "maven",
+    project_dir: Annotated[
+        str | None,
+        typer.Option("--project-dir", "-d", help="Path to project directory"),
+    ] = None,
+    project_key: Annotated[
+        str | None,
+        typer.Option("--project-key", "-k", help="SonarQube project key"),
+    ] = None,
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+    wait: Annotated[
+        bool,
+        typer.Option("--wait", "-w", help="Wait for scan completion"),
+    ] = False,
+    timeout: Annotated[
+        int,
+        typer.Option("--timeout", help="Scan timeout in seconds (default: 600)"),
+    ] = 600,
+) -> None:
+    """Run a local code quality scan.
+
+    Examples:
+        # Maven scan
+        vds-sonarqube scan --type maven --project-dir /path/to/project --project-key my-project
+
+        # Sonar-scanner
+        vds-sonarqube scan --type scanner --project-dir /path/to/project --project-key my-project
+
+        # With branch
+        vds-sonarqube scan --type maven --project-dir . --project-key my-project --branch main --wait
+    """
+    from vds_sonarqube_orchestrator.scanner import SonarqubeScanner
+
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        settings = load_settings(strict=True)
+        scanner = SonarqubeScanner(settings)
+
+        project_path = Path(project_dir)
+        if not project_path.exists():
+            out.output_error(f"Project directory does not exist: {project_dir}")
+            raise typer.Exit(1)
+
+        if scan_type == "maven":
+            out.output_info(f"Running Maven scan for {project_key}...")
+            task_id = scanner.scan_maven(
+                project_path,
+                project_key,
+                branch=branch,
+                wait=wait,
+                timeout=timeout,
+            )
+        elif scan_type == "scanner":
+            out.output_info(f"Running sonar-scanner for {project_key}...")
+            task_id = scanner.scan_scanner(
+                project_path,
+                project_key,
+                branch=branch,
+                wait=wait,
+                timeout=timeout,
+            )
+        else:
+            out.output_error(f"Unknown scan type: {scan_type}. Use 'maven' or 'scanner'")
+            raise typer.Exit(1)
+
+        out.output_success("Scan initiated successfully")
+        if task_id:
+            out.print(f"Task ID: {task_id}")
+
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Task Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("task")
+def task_cmd(
+    ctx: typer.Context,
+    status: Annotated[
+        bool,
+        typer.Option("--status", help="Show task status subcommand"),
+    ] = False,
+    id: Annotated[
+        str | None,
+        typer.Option("--id", help="Task ID (for status subcommand)"),
+    ] = None,
+) -> None:
+    """Get task status or show task help."""
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    if not status:
+        out.output_info("Use 'vds-sonarqube task --status --id <TASK_ID>' to check task status")
+        raise typer.Exit(0)
+
+    if not id:
+        out.output_error("--id is required when using --status")
+        raise typer.Exit(1)
+
+    try:
+        with _get_client() as client:
+            result = client.get_task_info(id)
+            out.output_json(result)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+    except VDSClientError as exc:
+        _handle_error(exc, out)
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Migration Command
+# -----------------------------------------------------------------------------
+
+
+@app.command("migrate-env")
+def migrate_env_cmd(
+    ctx: typer.Context,
+    source: Annotated[
+        str,
+        typer.Option("--source", "-s", help="Source directory containing .env file"),
+    ] = ".",
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview changes without applying"),
+    ] = False,
+) -> None:
+    """Migrate SonarQube credentials from project .env to the shared VDS env file.
+
+    Copies SONAR_* variables from project .env to VDS_SONAR_* in the shared VDS env file.
+
+    Examples:
+        # Preview migration
+        vds-sonarqube migrate-env --source EKYC-project/ekyc-business --dry-run
+
+        # Apply migration
+        vds-sonarqube migrate-env --source EKYC-project/ekyc-business
+    """
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+
+    source_dir = Path(source).resolve()
+    source_env = source_dir / ".env"
+
+    if not source_env.exists():
+        out.output_error(f".env file not found in: {source_dir}")
+        raise typer.Exit(1)
+
+    # Read source .env
+    source_vars: dict[str, str] = {}
+    with open(source_env) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith("SONAR_") and "=" in line:
+                key, value = line.split("=", 1)
+                source_vars[key] = value
+
+    if not source_vars:
+        out.output_error("No SONAR_* variables found in source .env")
+        raise typer.Exit(0)
+
+    # Build target variables
+    target_mappings = {
+        "SONAR_TOKEN": "VDS_SONAR_TOKEN",
+        "SONAR_HOST_URL": "VDS_SONAR_HOST_URL",
+        "SONAR_PROJECT_KEY": "VDS_SONAR_PROJECT_KEY",
+        "SONAR_BRANCH_NAME": "VDS_SONAR_BRANCH_NAME",
+        "SONAR_USER": "VDS_SONAR_USER",
+        "SONAR_PASSWORD": "VDS_SONAR_PASSWORD",
+    }
+
+    target_vars: dict[str, str] = {}
+    for src_key, tgt_key in target_mappings.items():
+        if src_key in source_vars:
+            target_vars[tgt_key] = source_vars[src_key]
+
+    # Show preview
+    out.print("[bold]Migration Preview:[/bold]")
+    for key, value in target_vars.items():
+        display_value = f"{value[:20]}..." if len(value) > 20 else value
+        if "PASSWORD" in key or "TOKEN" in key:
+            display_value = "***"
+        out.print(f"  {key} = {display_value}")
+
+    target_env_path = get_shared_env_path()
+
+    if dry_run:
+        out.print("\n[yellow]Dry run mode - no changes made[/yellow]")
+        out.print(f"Target file: {target_env_path}")
+        raise typer.Exit(0)
+
+    # Create backup
+    if target_env_path.exists():
+        backup_path = target_env_path.with_suffix(f".env.backup.{int(time.time())}")
+        shutil.copy2(target_env_path, backup_path)
+        out.print(f"[dim]Backup created: {backup_path}[/dim]")
+
+    # Ensure target directory exists
+    target_env_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Append new variables to target .env
+    with open(target_env_path, "a") as f:
+        f.write("\n# SonarQube Orchestrator (migrated from project .env)\n")
+        for key, value in target_vars.items():
+            f.write(f"{key}={value}\n")
+
+    out.output_success("Migration complete")
+    out.print(f"Updated: {target_env_path}")
+
+
+# -----------------------------------------------------------------------------
+# SCA (External Tool) Commands
+# -----------------------------------------------------------------------------
+
+
+@app.command("sca-status")
+def sca_status_cmd(
+    ctx: typer.Context,
+    install_guide: Annotated[
+        bool,
+        typer.Option("--install-guide", help="Show installation guide for SCA tools"),
+    ] = False,
+) -> None:
+    """Show available SCA tools and their installation status.
+
+    Examples:
+        vds-sonarqube sca-status
+        vds-sonarqube sca-status --install-guide
+    """
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        client = _get_sca_client()
+        tools = client.detect_available_tools()
+
+        if install_guide:
+            out.output_json({"install_guide": client.get_installation_guide()})
+            raise typer.Exit(0)
+
+        out.output_json({name: info.to_dict() for name, info in tools.items()})
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+
+
+@app.command("dependencies")
+def dependencies_cmd(
+    ctx: typer.Context,
+    project_dir: Annotated[
+        str,
+        typer.Option("--project-dir", "-d", help="Directory to scan (default: current directory)"),
+    ] = ".",
+    tool: Annotated[
+        str,
+        typer.Option("--tool", "-t", help="Tool to use (auto, snyk, trivy, grype)"),
+    ] = "auto",
+    severities: Annotated[
+        str | None,
+        typer.Option("--severities", "-s", help="Filter by severities (CRITICAL,HIGH,MEDIUM,LOW)"),
+    ] = None,
+) -> None:
+    """Scan dependencies for vulnerabilities using external SCA tools.
+
+    Examples:
+        vds-sonarqube dependencies --project-dir /path/to/project
+        vds-sonarqube dependencies --tool trivy --severities CRITICAL,HIGH
+    """
+    from vds_sonarqube_orchestrator.external_sca import (
+        SCAError,
+        ToolNotAvailableError,
+    )
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        client = _get_sca_client()
+        project_path = Path(project_dir).resolve()
+
+        if not project_path.exists():
+            out.output_error(f"Directory does not exist: {project_path}")
+            raise typer.Exit(1)
+
+        sev_list = severities.split(",") if severities else None
+        tool_name = None if tool == "auto" else tool
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Scanning {project_path} for vulnerabilities...")
+
+        report = client.scan_dependencies(project_path, tool=tool_name, severities=sev_list)
+        out.output_json(report.to_dict())
+
+    except ToolNotAvailableError as exc:
+        out.output_error(
+            str(exc),
+            hint="Run 'vds-sonarqube sca-status --install-guide' for installation help",
+        )
+        raise typer.Exit(1)
+    except SCAError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+
+
+@app.command("sbom")
+def sbom_cmd(
+    ctx: typer.Context,
+    project_dir: Annotated[
+        str,
+        typer.Option("--project-dir", "-d", help="Directory to scan (default: current directory)"),
+    ] = ".",
+    sbom_format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="SBOM format (cyclonedx, spdx)"),
+    ] = "cyclonedx",
+    tool: Annotated[
+        str,
+        typer.Option("--tool", "-t", help="Tool to use (auto, syft, trivy)"),
+    ] = "auto",
+    output: Annotated[
+        str | None,
+        typer.Option("--output", "-o", help="Output file path (default: stdout)"),
+    ] = None,
+) -> None:
+    """Generate Software Bill of Materials (SBOM) for a project.
+
+    Examples:
+        vds-sonarqube sbom --project-dir /path/to/project
+        vds-sonarqube sbom --format spdx --output sbom.json
+    """
+    from vds_sonarqube_orchestrator.external_sca import (
+        SCAError,
+        ToolNotAvailableError,
+    )
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        client = _get_sca_client()
+        project_path = Path(project_dir).resolve()
+
+        if not project_path.exists():
+            out.output_error(f"Directory does not exist: {project_path}")
+            raise typer.Exit(1)
+
+        tool_name = None if tool == "auto" else tool
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Generating {sbom_format.upper()} SBOM for {project_path}...")
+
+        sbom = client.generate_sbom(project_path, sbom_format=sbom_format, tool=tool_name)
+
+        if output:
+            output_path = Path(output)
+            with open(output_path, "w") as f:
+                json.dump(sbom.raw_output, f, indent=2)
+            if not cli_ctx.quiet:
+                out.output_success(f"SBOM saved to {output_path}")
+        elif cli_ctx.json_only:
+            out.output_json(sbom.raw_output)
+        else:
+            out.output_json(sbom.to_dict())
+
+    except ToolNotAvailableError as exc:
+        out.output_error(
+            str(exc),
+            hint="Run 'vds-sonarqube sca-status --install-guide' for installation help",
+        )
+        raise typer.Exit(1)
+    except SCAError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+
+
+@app.command("dependencies-check")
+def dependencies_check_cmd(
+    ctx: typer.Context,
+    project_dir: Annotated[
+        str,
+        typer.Option("--project-dir", "-d", help="Directory to scan (default: current directory)"),
+    ] = ".",
+    fail_on: Annotated[
+        str,
+        typer.Option("--fail-on", help="Minimum severity to fail (CRITICAL, HIGH, MEDIUM, LOW)"),
+    ] = "HIGH",
+    max_vulns: Annotated[
+        int,
+        typer.Option("--max-vulns", help="Maximum allowed vulnerabilities (0 = fail on any)"),
+    ] = 0,
+    tool: Annotated[
+        str,
+        typer.Option("--tool", "-t", help="Tool to use (auto, snyk, trivy, grype)"),
+    ] = "auto",
+) -> None:
+    """Check dependency quality gate (fail on vulnerabilities).
+
+    Exit code 0 = passed, 1 = failed or error.
+
+    Examples:
+        vds-sonarqube dependencies-check --project-dir /path/to/project
+        vds-sonarqube dependencies-check --fail-on CRITICAL --max-vulns 5
+    """
+    from vds_sonarqube_orchestrator.external_sca import (
+        SCAError,
+        ToolNotAvailableError,
+    )
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        client = _get_sca_client()
+        project_path = Path(project_dir).resolve()
+
+        if not project_path.exists():
+            out.output_error(f"Directory does not exist: {project_path}")
+            raise typer.Exit(1)
+
+        tool_name = None if tool == "auto" else tool
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Checking dependency quality gate for {project_path}...")
+
+        result = client.check_quality_gate(
+            project_path,
+            fail_threshold=fail_on.upper(),
+            max_vulnerabilities=max_vulns,
+            tool=tool_name,
+        )
+        out.output_json(result.to_dict())
+        raise typer.Exit(0 if result.passed else 1)
+
+    except ToolNotAvailableError as exc:
+        out.output_error(
+            str(exc),
+            hint="Run 'vds-sonarqube sca-status --install-guide' for installation help",
+        )
+        raise typer.Exit(1)
+    except SCAError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(
+            f"Configuration error: {exc}",
+            hint=f"Check VDS_SONAR_* variables in {get_shared_env_path()}",
+        )
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# PR Integration Commands (Phase 2)
+# -----------------------------------------------------------------------------
+
+
+@app.command("pr-comment")
+def pr_comment_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str,
+        typer.Option("--project", "-p", help="Bitbucket project key"),
+    ],
+    repo: Annotated[
+        str,
+        typer.Option("--repo", "-r", help="Repository slug"),
+    ],
+    pr_id: Annotated[
+        int,
+        typer.Option("--pr", help="Pull request ID"),
+    ],
+    sonar_project: Annotated[
+        str | None,
+        typer.Option(
+            "--sonar-project",
+            "-s",
+            help="SonarQube project key (defaults to VDS_SONAR_PROJECT_KEY)",
+        ),
+    ] = None,
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name for analysis"),
+    ] = None,
+) -> None:
+    """Decorate a PR with SonarQube analysis results using Bitbucket Code Insights.
+
+    Examples:
+        vds-sonarqube pr-comment --project EKYC --repo ekyc-business --pr 154
+        vds-sonarqube pr-comment -p EKYC -r ekyc-business --pr 154 --sonar-project ekyc-business
+    """
+    from vds_sonarqube_orchestrator.pr import PRDecoratorError, SonarqubePRDecorator
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        sonar_settings = load_settings(strict=True)
+
+        from vds_bitbucket_orchestrator.config import load_settings as load_bb_settings
+
+        bb_settings = load_bb_settings(strict=True)
+        decorator = SonarqubePRDecorator(sonar_settings, bb_settings)
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Decorating PR #{pr_id} with SonarQube results...")
+
+        result = decorator.decorate_pr(
+            project_key=project,
+            repo_slug=repo,
+            pr_id=pr_id,
+            sonar_project_key=sonar_project,
+            branch=branch,
+        )
+        out.output_json(result.to_dict())
+        raise typer.Exit(0 if result.success else 1)
+
+    except PRDecoratorError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except ImportError:
+        out.output_error(
+            "vds-bitbucket-orchestrator is required for PR integration",
+            hint="Install with: uv add vds-bitbucket-orchestrator",
+        )
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+@app.command("pr-status")
+def pr_status_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str,
+        typer.Option("--project", "-p", help="SonarQube project key"),
+    ],
+    _branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name (reserved for future use)"),
+    ] = None,
+    wait: Annotated[
+        bool,
+        typer.Option("--wait", "-w", help="Wait for analysis to complete"),
+    ] = False,
+    timeout: Annotated[
+        int,
+        typer.Option("--timeout", "-t", help="Timeout in seconds when waiting"),
+    ] = 300,
+) -> None:
+    """Check PR analysis status for a project/branch.
+
+    Examples:
+        vds-sonarqube pr-status --project ekyc-business
+        vds-sonarqube pr-status --project ekyc-business --branch feature/new --wait
+    """
+    from vds_sonarqube_orchestrator.pr import (
+        PRAnalysisStatus,
+        PRAnalysisTimeoutError,
+    )
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        sonar_settings = load_settings(strict=True)
+
+        class StatusChecker:
+            def __init__(self, settings):
+                self._settings = settings
+                self._client = None
+
+            def _get_client(self):
+                if self._client is None:
+                    self._client = SonarqubeClient(self._settings)
+                return self._client
+
+        checker = StatusChecker(sonar_settings)
+
+        if wait:
+            if not cli_ctx.quiet:
+                out.output_info(f"Waiting for analysis to complete (timeout: {timeout}s)...")
+
+            start_time = time.time()
+            while True:
+                elapsed = time.time() - start_time
+                if elapsed > timeout:
+                    raise PRAnalysisTimeoutError(f"Analysis did not complete within {timeout}s")
+
+                with checker._get_client() as client:
+                    tasks = client.get_ce_activity(project, limit=1)
+
+                if tasks:
+                    task = tasks[0]
+                    status_val = task.get("status", "UNKNOWN")
+                    if status_val in ("SUCCESS", "FAILED", "CANCELED"):
+                        result = PRAnalysisStatus(
+                            task_id=task.get("id", ""),
+                            status=status_val,
+                            component_key=task.get("componentKey"),
+                            analysis_id=task.get("analysisId"),
+                            error_message=task.get("errorMessage"),
+                        )
+                        break
+
+                time.sleep(5)
+        else:
+            with checker._get_client() as client:
+                tasks = client.get_ce_activity(project, limit=1)
+
+            if not tasks:
+                out.output_json({"status": "NO_ANALYSIS", "message": "No analysis found"})
+                raise typer.Exit(0)
+
+            task = tasks[0]
+            result = PRAnalysisStatus(
+                task_id=task.get("id", ""),
+                status=task.get("status", "UNKNOWN"),
+                component_key=task.get("componentKey"),
+                analysis_id=task.get("analysisId"),
+                error_message=task.get("errorMessage"),
+            )
+
+        out.output_json(result.to_dict())
+        raise typer.Exit(0 if result.is_success else 1)
+
+    except PRAnalysisTimeoutError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Batch Operations Commands (Phase 3)
+# -----------------------------------------------------------------------------
+
+
+@app.command("batch-qualitygate")
+def batch_qualitygate_cmd(
+    ctx: typer.Context,
+    projects: Annotated[
+        str,
+        typer.Option("--projects", "-p", help="Comma-separated project keys"),
+    ],
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+    fail_on_any: Annotated[
+        bool,
+        typer.Option("--fail-on-any", help="Exit 1 if any quality gate fails"),
+    ] = False,
+    concurrency: Annotated[
+        int,
+        typer.Option("--concurrency", "-c", help="Number of parallel requests"),
+    ] = 3,
+) -> None:
+    """Check quality gates for multiple projects in parallel.
+
+    Examples:
+        vds-sonarqube batch-qualitygate --projects "proj1,proj2,proj3"
+        vds-sonarqube batch-qualitygate -p "proj1,proj2" --fail-on-any
+    """
+    from vds_sonarqube_orchestrator.batch import BatchExecutor
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        settings = load_settings(strict=True)
+        executor = BatchExecutor(settings, concurrency=concurrency)
+        project_list = [p.strip() for p in projects.split(",") if p.strip()]
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Checking quality gates for {len(project_list)} projects...")
+
+        result = executor.batch_quality_gates(project_list, branch)
+        out.output_json(result.to_dict())
+
+        any_failed = any(not pr.data.get("passed", False) for pr in result.results if pr.success)
+        raise typer.Exit(1 if fail_on_any and any_failed else 0)
+
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+@app.command("batch-issues")
+def batch_issues_cmd(
+    ctx: typer.Context,
+    projects: Annotated[
+        str,
+        typer.Option("--projects", "-p", help="Comma-separated project keys"),
+    ],
+    severities: Annotated[
+        str | None,
+        typer.Option(
+            "--severities", "-s", help="Filter by severities (BLOCKER,CRITICAL,MAJOR,MINOR,INFO)"
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Max issues per project"),
+    ] = 100,
+    concurrency: Annotated[
+        int,
+        typer.Option("--concurrency", "-c", help="Number of parallel requests"),
+    ] = 3,
+) -> None:
+    """Fetch issues for multiple projects in parallel.
+
+    Examples:
+        vds-sonarqube batch-issues --projects "proj1,proj2,proj3"
+        vds-sonarqube batch-issues -p "proj1,proj2" --severities CRITICAL,MAJOR
+    """
+    from vds_sonarqube_orchestrator.batch import BatchExecutor
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        settings = load_settings(strict=True)
+        executor = BatchExecutor(settings, concurrency=concurrency)
+        project_list = [p.strip() for p in projects.split(",") if p.strip()]
+        sev_list = [s.strip() for s in severities.split(",")] if severities else None
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Fetching issues for {len(project_list)} projects...")
+
+        result = executor.batch_issues(project_list, severities=sev_list, limit_per_project=limit)
+        out.output_json(result.to_dict())
+        raise typer.Exit(0)
+
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Report Generation Commands (Phase 4)
+# -----------------------------------------------------------------------------
+
+
+@app.command("report")
+def report_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str,
+        typer.Option("--project", "-p", help="SonarQube project key"),
+    ],
+    output: Annotated[
+        str,
+        typer.Option("--output", "-o", help="Output file path"),
+    ],
+    report_format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Report format (html, pdf)"),
+    ] = "html",
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+    trends: Annotated[
+        bool,
+        typer.Option("--trends", help="Include trend analysis"),
+    ] = False,
+    trend_days: Annotated[
+        int,
+        typer.Option("--trend-days", help="Days of trend data to include"),
+    ] = 30,
+) -> None:
+    """Generate quality report for a project.
+
+    Examples:
+        vds-sonarqube report --project ekyc-business --output report.html
+        vds-sonarqube report -p ekyc-business -o report.pdf --format pdf --trends
+    """
+    from vds_sonarqube_orchestrator.reports import ReportError, SonarqubeReportGenerator
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        settings = load_settings(strict=True)
+        generator = SonarqubeReportGenerator(settings)
+        output_path = Path(output)
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Generating {report_format.upper()} report for {project}...")
+
+        if report_format.lower() == "pdf":
+            result_path = generator.generate_pdf_report(
+                project_key=project,
+                output_path=output_path,
+                branch=branch,
+                include_trends=trends,
+                trend_days=trend_days,
+            )
+        else:
+            result_path = generator.generate_html_report(
+                project_key=project,
+                output_path=output_path,
+                branch=branch,
+                include_trends=trends,
+                trend_days=trend_days,
+            )
+
+        out.output_json({"success": True, "output": str(result_path)})
+        raise typer.Exit(0)
+
+    except ReportError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Webhook Commands (Phase 5)
+# -----------------------------------------------------------------------------
+
+webhook_app = typer.Typer(name="webhook", help="Webhook management commands.")
+app.add_typer(webhook_app)
+
+
+@webhook_app.command("register")
+def webhook_register_cmd(
+    ctx: typer.Context,
+    url: Annotated[
+        str,
+        typer.Option("--url", "-u", help="Webhook URL"),
+    ],
+    events: Annotated[
+        str,
+        typer.Option(
+            "--events",
+            "-e",
+            help="Comma-separated events (scan_complete,quality_gate_change)",
+        ),
+    ] = "scan_complete",
+    secret: Annotated[
+        str | None,
+        typer.Option("--secret", "-s", help="HMAC secret for signing"),
+    ] = None,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Limit to specific project"),
+    ] = None,
+) -> None:
+    """Register a new webhook.
+
+    Examples:
+        vds-sonarqube webhook register --url https://example.com/hook --events scan_complete
+        vds-sonarqube webhook register -u https://example.com/hook -e scan_complete,quality_gate_change -s mysecret
+    """
+    from vds_sonarqube_orchestrator.webhooks import WebhookError, WebhookManager
+
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    try:
+        manager = WebhookManager()
+        event_list = [e.strip() for e in events.split(",")]
+        webhook = manager.register_webhook(
+            url=url, events=event_list, secret=secret, project_key=project
+        )
+        out.output_json(webhook.to_dict())
+    except WebhookError as exc:
+        out.output_error(str(exc))
+        raise typer.Exit(1)
+
+
+@webhook_app.command("list")
+def webhook_list_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Filter by project"),
+    ] = None,
+) -> None:
+    """List registered webhooks.
+
+    Examples:
+        vds-sonarqube webhook list
+        vds-sonarqube webhook list --project ekyc-business
+    """
+    from vds_sonarqube_orchestrator.webhooks import WebhookManager
+
+    out = OutputManager(CLIContext.from_typer_context(ctx))
+    manager = WebhookManager()
+    webhooks = manager.list_webhooks(project_key=project)
+    out.output_json([wh.to_dict() for wh in webhooks])
+
+
+@webhook_app.command("delete")
+def webhook_delete_cmd(
+    ctx: typer.Context,
+    webhook_id: Annotated[
+        str,
+        typer.Option("--id", help="Webhook ID to delete"),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip confirmation"),
+    ] = False,
+) -> None:
+    """Delete a webhook.
+
+    Examples:
+        vds-sonarqube webhook delete --id abc123 --yes
+    """
+    from vds_sonarqube_orchestrator.webhooks import WebhookManager
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    manager = WebhookManager()
+
+    if not yes and not cli_ctx.json_only:
+        confirm = typer.confirm(f"Delete webhook {webhook_id}?")
+        if not confirm:
+            raise typer.Exit(0)
+
+    deleted = manager.delete_webhook(webhook_id)
+    out.output_json({"deleted": deleted, "id": webhook_id})
+    raise typer.Exit(0 if deleted else 1)
+
+
+# -----------------------------------------------------------------------------
+# Diff Analysis Commands (Phase 5)
+# -----------------------------------------------------------------------------
+
+
+@app.command("diff")
+def diff_cmd(
+    ctx: typer.Context,
+    project: Annotated[
+        str,
+        typer.Option("--project", "-p", help="SonarQube project key"),
+    ],
+    before_branch: Annotated[
+        str,
+        typer.Option("--before", help="Before branch name (e.g., main, release)"),
+    ],
+    after_branch: Annotated[
+        str,
+        typer.Option("--after", help="After branch name (e.g., feature/new)"),
+    ] = "main",
+) -> None:
+    """Compare issues between two branches.
+
+    Examples:
+        vds-sonarqube diff --project ekyc-business --before main --after feature/new
+        vds-sonarqube diff -p ekyc-business --before release --after develop
+    """
+    from vds_sonarqube_orchestrator.diff import DiffAnalyzer
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        settings = load_settings(strict=True)
+        analyzer = DiffAnalyzer(settings)
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Analyzing diff for {project}...")
+
+        result = analyzer.compare_branches(project, before_branch, after_branch)
+        out.output_json(result.to_dict())
+        raise typer.Exit(0)
+
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Portfolio Commands (Phase 5)
+# -----------------------------------------------------------------------------
+
+
+@app.command("portfolio")
+def portfolio_cmd(
+    ctx: typer.Context,
+    projects: Annotated[
+        str,
+        typer.Option("--projects", "-p", help="Comma-separated project keys"),
+    ],
+    by_severity: Annotated[
+        bool,
+        typer.Option("--by-severity", help="Show breakdown by severity"),
+    ] = False,
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch name"),
+    ] = None,
+    top_issues: Annotated[
+        int,
+        typer.Option("--top-issues", help="Show top N common issues"),
+    ] = 0,
+) -> None:
+    """Aggregate metrics across multiple projects.
+
+    Examples:
+        vds-sonarqube portfolio --projects "proj1,proj2,proj3"
+        vds-sonarqube portfolio -p "proj1,proj2" --by-severity
+    """
+    from vds_sonarqube_orchestrator.portfolio import PortfolioManager
+
+    cli_ctx = CLIContext.from_typer_context(ctx)
+    out = OutputManager(cli_ctx)
+    try:
+        settings = load_settings(strict=True)
+        manager = PortfolioManager(settings)
+        project_list = [p.strip() for p in projects.split(",") if p.strip()]
+
+        if not cli_ctx.quiet:
+            out.output_info(f"Aggregating metrics for {len(project_list)} projects...")
+
+        result = manager.get_portfolio_metrics(project_keys=project_list, branch=branch)
+
+        if by_severity:
+            result.by_severity = manager.get_issues_by_severity(project_list)
+
+        top_issues_list = []
+        if top_issues > 0:
+            top_issues_list = manager.get_top_issues(project_list, limit=top_issues)
+
+        output_data = result.to_dict()
+        if top_issues_list:
+            output_data["top_issues"] = [ti.to_dict() for ti in top_issues_list]
+        out.output_json(output_data)
+        raise typer.Exit(0)
+
+    except SettingsError as exc:
+        out.output_error(f"Configuration error: {exc}")
+        raise typer.Exit(1)
+
+
+# -----------------------------------------------------------------------------
+# Entry Point
+# -----------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    app()