Skip to content

netresearch/jira-skill / skills/jira-communication

jira-communication

Flagged

Use when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC.

FileKindSize
AGENTS.mdmarkdown2.5 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md10.4 KB
evals/evals.jsonconfig7.6 KB
references/agile.mdmarkdown1.9 KB
references/attachments.mdmarkdown4.7 KB
references/comments.mdmarkdown14.4 KB
references/creation.mdmarkdown4.0 KB
references/fields-and-users.mdmarkdown7.7 KB
references/intent-verbs.mdmarkdown13.5 KB
references/issue-editing.mdmarkdown11.6 KB
references/jql-cookbook.mdmarkdown8.0 KB
references/jql-quick-reference.mdmarkdown6.3 KB
references/links.mdmarkdown7.8 KB
references/multi-profile.mdmarkdown3.9 KB
references/no-editorializing.mdmarkdown2.3 KB
references/qa-gather.mdmarkdown12.1 KB
references/troubleshooting.mdmarkdown12.0 KB
references/versions.mdmarkdown7.7 KB
references/watchers.mdmarkdown3.9 KB
references/worklog.mdmarkdown8.6 KB
scripts/core/jira-attachment.pyexecutablescript21.2 KB
scripts/core/jira-issue.pyexecutablescript50.6 KB
scripts/core/jira-search.pyexecutablescript9.6 KB
scripts/core/jira-setup.pyexecutablescript20.0 KB
scripts/core/jira-validate.pyexecutablescript14.2 KB
scripts/core/jira-worklog.pyexecutablescript15.5 KB
scripts/lib/__init__.pyscript742 B
scripts/lib/changelog.pyscript8.0 KB
scripts/lib/client.pyscript26.4 KB
scripts/lib/config.pyscript15.9 KB
scripts/lib/errors.pyscript1.8 KB
scripts/lib/input.pyscript3.5 KB
scripts/lib/jql.pyscript375 B
scripts/lib/markup.pyscript33.2 KB
scripts/lib/markup_cli.pyscript11.3 KB
scripts/lib/output.pyscript6.9 KB
scripts/lib/preview.pyscript10.0 KB
scripts/lib/render.pyscript1.8 KB
scripts/lib/ticket_state.pyscript13.3 KB
scripts/lib/users.pyscript7.5 KB
scripts/utility/jira-fields.pyexecutablescript11.7 KB
scripts/utility/jira-link.pyexecutablescript42.9 KB
scripts/utility/jira-qa-gather.pyexecutablescript26.3 KB
scripts/utility/jira-user.pyexecutablescript9.3 KB
scripts/utility/jira-watchers.pyexecutablescript9.1 KB
scripts/utility/jira-weblink.pyexecutablescript11.2 KB
scripts/utility/jira-worklog-query.pyexecutablescript27.4 KB
scripts/workflow/jira-board.pyexecutablescript7.0 KB
scripts/workflow/jira-comment.pyexecutablescript19.2 KB
scripts/workflow/jira-create.pyexecutablescript24.3 KB
scripts/workflow/jira-move.pyexecutablescript23.5 KB
scripts/workflow/jira-sprint.pyexecutablescript8.1 KB
scripts/workflow/jira-transition.pyexecutablescript33.7 KB
scripts/workflow/jira-version.pyexecutablescript29.4 KB
scripts/workflow/tempo-account.pyexecutablescript9.1 KB

scripts/core/jira-validate.py

View on GitHub
#!/usr/bin/env -S uv run --script
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "atlassian-python-api>=3.41.0,<4",
#     "click>=8.1.0,<9",
#     "requests>=2.31.0,<3",
# ]
# ///
"""Jira environment validation - verify runtime, configuration, and connectivity."""

import shutil
import subprocess
import sys
from pathlib import Path

# ═══════════════════════════════════════════════════════════════════════════════
# Shared library import (TR1.1.1 - PYTHONPATH approach)
# ═══════════════════════════════════════════════════════════════════════════════
_script_dir = Path(__file__).parent
_lib_path = _script_dir.parent / "lib"
if _lib_path.exists():
    sys.path.insert(0, str(_lib_path.parent))

import json as json_module

import click
import requests
from lib.client import AuthenticationError, LazyJiraClient, SessionExpiredError, _sanitize_error
from lib.config import (
    DEFAULT_ENV_FILE,
    PROFILES_FILE,
    get_auth_mode,
    load_config,
    load_profiles,
    profile_to_config,
    resolve_is_cloud,
    validate_config,
)
from lib.output import error, format_table, success, warning

# ═══════════════════════════════════════════════════════════════════════════════
# Exit Codes (TR2.3)
# ═══════════════════════════════════════════════════════════════════════════════
EXIT_SUCCESS = 0
EXIT_RUNTIME_ERROR = 1
EXIT_CONFIG_ERROR = 2
EXIT_CONNECTION_ERROR = 3


def check_runtime(verbose: bool = False) -> tuple[bool, dict]:
    """Check runtime dependencies (D7)."""
    checks_passed = True
    info = {}

    # Check uv/uvx
    uv_path = shutil.which("uv")
    if uv_path:
        result = subprocess.run(["uv", "--version"], capture_output=True, text=True)  # nosec B603 B607
        uv_version = result.stdout.strip() if result.returncode == 0 else "unknown"
        info["uv_path"] = uv_path
        info["uv_version"] = uv_version
        if verbose:
            success(f"uv found: {uv_path} ({uv_version})")
    else:
        error(
            "Runtime check failed: 'uv' command not found",
            "To install uv, run:\n"
            "    pip install uv\n\n"
            "  Or visit: https://docs.astral.sh/uv/getting-started/installation/",
        )
        checks_passed = False

    # Check Python version
    py_version = sys.version_info
    info["python_version"] = f"{py_version.major}.{py_version.minor}.{py_version.micro}"
    if py_version >= (3, 11):
        if verbose:
            success(f"Python version: {py_version.major}.{py_version.minor}.{py_version.micro}")
    else:
        error(
            f"Python version {py_version.major}.{py_version.minor} < 3.11 required",
            "Please upgrade Python to 3.11 or later",
        )
        checks_passed = False

    return checks_passed, info


def check_environment(env_file: str | None, profile: str | None = None, verbose: bool = False) -> dict | None:
    """Check environment configuration."""
    try:
        config = load_config(env_file=env_file, profile=profile)
        errors = validate_config(config)

        if errors:
            for err in errors:
                error(f"Configuration error: {err}")
            return None

        if env_file and profile:
            warning("--profile is ignored because --env-file was provided")

        if verbose:
            if env_file:
                path = Path(env_file)
                success(f"Environment file: {path}")
            elif profile:
                success(f"Profile: {profile} (from {PROFILES_FILE})")
            else:
                # Detect whether profiles.json or legacy env file was used
                try:
                    profiles_data = load_profiles()
                    default_name = profiles_data.get("default", "unknown")
                    success(f"Profile: {default_name} (default from {PROFILES_FILE})")
                except (FileNotFoundError, ValueError):
                    success(f"Environment file: {DEFAULT_ENV_FILE}")
            success(f"JIRA_URL: {config['JIRA_URL']}")

            # Show auth mode-specific credentials
            auth_mode = get_auth_mode(config)
            if auth_mode == "pat":
                success("Auth mode: Personal Access Token (Server/DC)")
                success("JIRA_PERSONAL_TOKEN: ******* (hidden)")
            else:
                success("Auth mode: Username + API Token (Cloud)")
                success(f"JIRA_USERNAME: {config.get('JIRA_USERNAME', 'N/A')}")
                success("JIRA_API_TOKEN: ******* (hidden)")

            if "JIRA_CLOUD" in config:
                success(f"JIRA_CLOUD: {config['JIRA_CLOUD']}")

        return config

    except (FileNotFoundError, ValueError) as e:
        error(str(e))
        return None


def check_connectivity(
    config: dict, project: str | None, profile: str | None = None, env_file: str | None = None, verbose: bool = False
) -> tuple[bool, dict]:
    """Check connectivity and authentication."""
    url = config["JIRA_URL"]
    info = {"url": url}

    # Test server reachability
    try:
        response = requests.head(url, timeout=10, allow_redirects=True)
        info["server_reachable"] = True
        if verbose:
            success(f"Server reachable: {url} (status: {response.status_code})")
    except requests.exceptions.Timeout:
        error(
            f"Connection timeout: {url}",
            "The server did not respond within 10 seconds.\n  Check your network connection and JIRA_URL.",
        )
        return False, info
    except requests.exceptions.ConnectionError as e:
        error(f"Connection failed: {url}", f"Could not connect to the server.\n  Error: {_sanitize_error(str(e))}")
        return False, info

    # Test authentication
    try:
        client = LazyJiraClient(env_file=env_file, profile=profile)
        user = client.myself()
        display_name = user.get("displayName", user.get("name", "Unknown"))
        email = user.get("emailAddress", "N/A")
        info["user"] = display_name
        info["email"] = email

        if verbose:
            success(f"Authenticated as: {display_name} ({email})")

    except SessionExpiredError as e:
        error("Authentication failed", str(e))
        return False, info
    except AuthenticationError as e:
        error("Authentication failed", str(e))
        return False, info
    except Exception as e:
        error(
            "Authentication failed",
            f"Could not authenticate with the provided credentials.\n  Error: {_sanitize_error(str(e))}",
        )
        return False, info

    # Test project access (optional)
    if project:
        try:
            proj = client.project(project)
            info["project_access"] = project
            if verbose:
                success(f"Project access: {project} ({proj.get('name', 'Unknown')})")
            else:
                success(f"Project access verified: {project}")
        except Exception as e:
            warning(f"Could not access project {project}: {e}")

    return True, info


def validate_all_profiles(output_json: bool = False, verbose: bool = False) -> int:
    """Validate all profiles in ~/.jira/profiles.json.

    Returns:
        Exit code (0 = all passed, 2 = config error, 3 = connectivity error)
    """
    try:
        data = load_profiles()
    except (FileNotFoundError, ValueError) as e:
        error(str(e))
        return EXIT_CONFIG_ERROR

    profiles = data["profiles"]
    default_name = data.get("default", "")
    results = []

    for name, prof in profiles.items():
        row = {
            "Profile": name,
            "URL": prof.get("url", "N/A"),
            "Auth": prof.get("auth", "N/A"),
            "Projects": ", ".join(prof.get("projects", [])) if isinstance(prof.get("projects"), list) else "-",
            "Default": "Yes" if name == default_name else "",
        }

        try:
            config = profile_to_config(prof)
        except ValueError:
            row["Status"] = "CONFIG ERROR"
            results.append(row)
            continue

        errors = validate_config(config)
        if errors:
            row["Status"] = "CONFIG ERROR"
            results.append(row)
            continue

        # Quick connectivity check
        try:
            response = requests.head(config["JIRA_URL"], timeout=5, allow_redirects=True)
            if response.status_code < 400 or response.status_code in (401, 403):
                row["Status"] = "OK"
            else:
                row["Status"] = f"HTTP {response.status_code}"
        except Exception:
            row["Status"] = "UNREACHABLE"

        results.append(row)

    if output_json:
        print(json_module.dumps(results, indent=2))
    else:
        click.echo(f"Profiles from {PROFILES_FILE}:\n")
        print(format_table(results, ["Profile", "URL", "Auth", "Projects", "Status", "Default"]))
        click.echo()
        ok_count = sum(1 for r in results if r["Status"] == "OK")
        click.echo(f"{ok_count}/{len(results)} profiles reachable")

    # Differentiate exit codes: config errors (2) vs connectivity errors (3)
    has_config_errors = any(r["Status"] == "CONFIG ERROR" for r in results)
    has_connectivity_errors = any(r["Status"] not in ("OK", "CONFIG ERROR") for r in results)

    if has_connectivity_errors:
        return EXIT_CONNECTION_ERROR
    if has_config_errors:
        return EXIT_CONFIG_ERROR
    return EXIT_SUCCESS


@click.command()
@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
@click.option("--quiet", "-q", is_flag=True, help="Minimal output")
@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
@click.option("--project", "-p", help="Verify access to specific project")
@click.option("--env-file", type=click.Path(exists=False), help="Path to environment file")
@click.option("--profile", "-P", help="Validate a specific profile from ~/.jira/profiles.json")
@click.option("--all-profiles", is_flag=True, help="Validate all profiles in ~/.jira/profiles.json")
@click.option("--debug", is_flag=True, help="Show debug information on errors")
def main(
    output_json: bool,
    quiet: bool,
    verbose: bool,
    project: str | None,
    env_file: str | None,
    profile: str | None,
    all_profiles: bool,
    debug: bool,
):
    """Validate Jira environment configuration.

    Checks runtime dependencies, environment configuration, and connectivity
    to ensure the Jira CLI scripts will work correctly.

    \b
    Exit codes:
      0 - All checks passed
      1 - Runtime dependency missing
      2 - Environment configuration error
      3 - Connectivity/authentication failure

    \b
    Examples:
      # Validate default configuration
      uv run scripts/core/jira-validate.py --verbose

      # Validate a specific profile
      uv run scripts/core/jira-validate.py --profile mkk --verbose

      # Validate all profiles
      uv run scripts/core/jira-validate.py --all-profiles
    """
    # Handle --all-profiles mode
    if all_profiles:
        exit_code = validate_all_profiles(output_json=output_json, verbose=verbose)
        sys.exit(exit_code)

    result = {"status": "ok"}

    # Suppress verbose output if JSON or quiet mode
    show_verbose = verbose and not output_json and not quiet

    if show_verbose:
        click.echo("=" * 60)
        if profile:
            click.echo(f"Jira Environment Validation (profile: {profile})")
        else:
            click.echo("Jira Environment Validation")
        click.echo("=" * 60)
        click.echo()

    # Check 1: Runtime
    if show_verbose:
        click.echo("Runtime Checks:")
    runtime_ok, runtime_info = check_runtime(show_verbose)
    result["runtime"] = runtime_info
    if not runtime_ok:
        result["status"] = "error"
        result["error"] = "runtime_check_failed"
        if output_json:
            print(json_module.dumps(result, indent=2))
        elif quiet:
            print("error")
        sys.exit(EXIT_RUNTIME_ERROR)
    if show_verbose:
        click.echo()

    # Check 2: Environment
    if show_verbose:
        click.echo("Environment Checks:")
    config = check_environment(env_file, profile, show_verbose)
    if config is None:
        result["status"] = "error"
        result["error"] = "config_error"
        if output_json:
            print(json_module.dumps(result, indent=2))
        elif quiet:
            print("error")
        sys.exit(EXIT_CONFIG_ERROR)

    if profile:
        result["profile"] = profile
    result["url"] = config["JIRA_URL"]
    result["server_type"] = "cloud" if resolve_is_cloud(config) else "server"
    auth_mode = get_auth_mode(config)
    result["auth_mode"] = auth_mode
    if auth_mode == "cloud":
        result["username"] = config.get("JIRA_USERNAME", "N/A")
    if show_verbose:
        click.echo()

    # Check 3: Connectivity
    if show_verbose:
        click.echo("Connectivity Checks:")
    conn_ok, conn_info = check_connectivity(config, project, profile=profile, env_file=env_file, verbose=show_verbose)
    result["user"] = conn_info.get("user", "Unknown")
    if "project_access" in conn_info:
        result["project_access"] = conn_info["project_access"]
    if not conn_ok:
        result["status"] = "error"
        result["error"] = "connectivity_error"
        if output_json:
            print(json_module.dumps(result, indent=2))
        elif quiet:
            print("error")
        sys.exit(EXIT_CONNECTION_ERROR)
    if show_verbose:
        click.echo()

    # All passed
    if output_json:
        print(json_module.dumps(result, indent=2))
    elif quiet:
        print("ok")
    else:
        if show_verbose:
            click.echo("=" * 60)
        success("All validation checks passed!")
    sys.exit(EXIT_SUCCESS)


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall