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-setup.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",
# ]
# ///
"""Interactive Jira credential setup - configure authentication interactively."""

import os
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

import click
import requests
from atlassian import Jira
from lib.client import (
    JIRA_TIMEOUT,
    AuthenticationError,
    SessionExpiredError,
    _patch_session_for_response_validation,
    _sanitize_error,
)
from lib.config import DEFAULT_ENV_FILE, PROFILES_FILE, is_cloud_url, load_env
from lib.output import error, success, warning

# ═══════════════════════════════════════════════════════════════════════════════
# Exit Codes
# ═══════════════════════════════════════════════════════════════════════════════
EXIT_SUCCESS = 0
EXIT_USER_ABORT = 1
EXIT_VALIDATION_FAILED = 2


def detect_jira_type(url: str) -> str:
    """Detect if URL is Jira Cloud or Server/Data Center.

    Args:
        url: Jira instance URL

    Returns:
        'cloud' for Atlassian Cloud, 'server' for Server/DC
    """
    return "cloud" if is_cloud_url(url) else "server"


def validate_url(url: str) -> tuple[bool, str]:
    """Validate Jira URL is reachable.

    Args:
        url: URL to validate

    Returns:
        Tuple of (success, message)
    """
    if not url.startswith(("http://", "https://")):
        return False, "URL must start with http:// or https://"

    try:
        response = requests.head(url, timeout=10, allow_redirects=True)
        status = response.status_code
        # 405 = HEAD not allowed — fall back to GET
        if status == 405:
            response = requests.get(url, timeout=10, allow_redirects=True, stream=True)
            response.close()
            status = response.status_code
        if status < 400:
            return True, f"Server reachable (status: {status})"
        if status in (401, 403):
            return True, f"Server reachable, authentication required (status: {status})"
        if status < 500:
            return False, f"Client error when contacting server (status: {status})"
        return False, f"Server error (status: {status})"
    except requests.exceptions.Timeout:
        return False, "Connection timeout - server did not respond"
    except requests.exceptions.ConnectionError as e:
        return False, f"Connection failed: {_sanitize_error(str(e))}"


def validate_credentials(url: str, auth_type: str, **kwargs) -> tuple[bool, str]:
    """Validate Jira credentials by attempting authentication.

    Args:
        url: Jira instance URL
        auth_type: 'cloud' or 'server'
        **kwargs: Authentication credentials

    Returns:
        Tuple of (success, message/user_info)
    """
    try:
        if auth_type == "cloud":
            client = Jira(
                url=url,
                username=kwargs["username"],
                password=kwargs["api_token"],
                cloud=True,
                timeout=JIRA_TIMEOUT,
            )
        else:
            client = Jira(
                url=url,
                token=kwargs["personal_token"],
                timeout=JIRA_TIMEOUT,
            )

        _patch_session_for_response_validation(client, url)

        user = client.myself()
        if isinstance(user, dict):
            display_name = user.get("displayName", user.get("name", "Unknown"))
            email = user.get("emailAddress", "")
        else:
            user_str = str(user) if user else ""
            # Defensive fallback for mocked/unpatched clients where an HTML
            # 2FA/Secure Login page reaches this point instead of raising
            # SessionExpiredError from the response-validation hook.
            if user_str.lstrip().startswith(("<!DOCTYPE", "<html", "<HTML")):
                return False, (
                    "Two-factor authentication (2FA/Secure Login) intercepted the API call "
                    "or the session expired. Your PAT may not bypass 2FA on this instance. "
                    "Check Jira admin settings or create a new PAT with API access."
                )
            display_name = user_str or "Unknown"
            email = ""
        return True, f"{display_name}" + (f" ({email})" if email else "")

    except SessionExpiredError:
        return False, (
            "Two-factor authentication (2FA/Secure Login) intercepted the API call "
            "or the session expired. Your PAT may not bypass 2FA on this instance. "
            "Check Jira admin settings or create a new PAT with API access."
        )
    except AuthenticationError:
        return False, "Authentication failed - invalid credentials or insufficient permissions"
    except Exception as e:
        return False, f"Connection error: {_sanitize_error(str(e))}"


def write_env_file(path: Path, config: dict) -> None:
    """Write configuration to environment file.

    Security note: Credentials are stored in clear text, similar to standard
    credential files like ~/.netrc, ~/.npmrc, or ~/.aws/credentials. The file
    is protected by restrictive filesystem permissions (0600 - owner read/write
    only). This is an intentional design choice following common CLI tool patterns.

    Args:
        path: Path to write
        config: Configuration dictionary
    """
    lines = [
        "# Jira CLI Configuration",
        "# Generated by jira-setup.py",
        "# Security: This file contains credentials and is protected by 0600 permissions",
        "",
    ]

    for key, value in config.items():
        if value:
            lines.append(f"{key}={value}")

    lines.append("")

    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write("\n".join(lines))
    os.chmod(path, 0o600)


def write_profile(profile_name: str, profile_data: dict) -> None:
    """Write or update a profile in ~/.jira/profiles.json.

    Args:
        profile_name: Name for the profile
        profile_data: Profile configuration dict (url, auth, token/credentials, projects)
    """
    profiles_dir = PROFILES_FILE.parent

    # Load existing or create new
    if PROFILES_FILE.exists():
        try:
            data = json.loads(PROFILES_FILE.read_text())
        except json.JSONDecodeError:
            warning(f"{PROFILES_FILE} is corrupted. Creating backup and starting fresh.")
            PROFILES_FILE.replace(PROFILES_FILE.with_suffix(".json.bak"))
            data = {"version": 1, "profiles": {}}
        else:
            # Validate structure: must be a dict with a 'profiles' dict
            if not isinstance(data, dict) or not isinstance(data.get("profiles"), dict):
                warning(f"{PROFILES_FILE} has invalid structure. Creating backup and starting fresh.")
                PROFILES_FILE.replace(PROFILES_FILE.with_suffix(".json.bak"))
                data = {"version": 1, "profiles": {}}
    else:
        profiles_dir.mkdir(parents=True, exist_ok=True)
        data = {"version": 1, "profiles": {}}

    # Update profile
    data["profiles"][profile_name] = profile_data

    # Set default if first profile
    if "default" not in data or not data["default"]:
        data["default"] = profile_name

    # Write with restricted permissions from creation (no race condition)
    fd = os.open(PROFILES_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(json.dumps(data, indent=2) + "\n")
    os.chmod(PROFILES_FILE, 0o600)


def migrate_env_to_profile() -> None:
    """Migrate ~/.env.jira to ~/.jira/profiles.json."""
    if not DEFAULT_ENV_FILE.exists():
        error(f"No env file found at {DEFAULT_ENV_FILE}")
        sys.exit(EXIT_VALIDATION_FAILED)

    if PROFILES_FILE.exists():
        click.echo(f"⚠ Profiles file already exists: {PROFILES_FILE}")
        if not click.confirm("Add legacy config as 'default' profile?", default=False):
            click.echo("\nMigration cancelled.")
            sys.exit(EXIT_USER_ABORT)

    config = load_env()

    url = config.get("JIRA_URL", "")
    profile_data = {"url": url}

    if config.get("JIRA_PERSONAL_TOKEN"):
        profile_data["auth"] = "pat"
        profile_data["token"] = config["JIRA_PERSONAL_TOKEN"]
    else:
        profile_data["auth"] = "cloud"
        profile_data["username"] = config.get("JIRA_USERNAME", "")
        profile_data["api_token"] = config.get("JIRA_API_TOKEN", "")

    cloud_setting = config.get("JIRA_CLOUD", "").strip().lower()
    if cloud_setting in ("true", "false"):
        profile_data["cloud"] = cloud_setting == "true"

    profile_data["projects"] = []

    write_profile("default", profile_data)
    success(f"Migrated {DEFAULT_ENV_FILE} → {PROFILES_FILE} (profile: 'default')")
    click.echo()
    click.echo("You can now add project keys to the profile:")
    click.echo(f'  Edit {PROFILES_FILE} and add project keys to "projects": []')


@click.command()
@click.option("--url", help="Jira instance URL (will prompt if not provided)")
@click.option(
    "--type", "jira_type", type=click.Choice(["cloud", "server", "auto"]), default="auto", help="Jira deployment type"
)
@click.option(
    "--output",
    "-o",
    type=click.Path(),
    default=str(DEFAULT_ENV_FILE),
    help=f"Output file path (default: {DEFAULT_ENV_FILE})",
)
@click.option("--force", "-f", is_flag=True, help="Overwrite existing file without prompting")
@click.option("--test-only", is_flag=True, help="Test credentials without saving")
@click.option("--profile", "-P", help="Save as named profile in ~/.jira/profiles.json")
@click.option("--projects", help="Comma-separated project keys for the profile")
@click.option("--migrate", is_flag=True, help="Migrate ~/.env.jira to profiles.json")
def main(
    url: str | None,
    jira_type: str,
    output: str,
    force: bool,
    test_only: bool,
    profile: str | None,
    projects: str | None,
    migrate: bool,
):
    """Interactive Jira credential setup.

    Guides you through configuring Jira authentication credentials
    and validates them before saving to ~/.env.jira or ~/.jira/profiles.json.

    Supports both Jira Cloud (username + API token) and
    Jira Server/Data Center (Personal Access Token).

    \b
    Examples:
      # Interactive setup (legacy env file)
      uv run scripts/core/jira-setup.py

      # Setup as named profile
      uv run scripts/core/jira-setup.py --profile mkk --url https://jira.example.com

      # Pre-fill URL
      uv run scripts/core/jira-setup.py --url https://company.atlassian.net

      # Test credentials without saving
      uv run scripts/core/jira-setup.py --test-only

      # Migrate existing .env.jira to profiles.json
      uv run scripts/core/jira-setup.py --migrate
    """
    # Handle migration mode
    if migrate:
        click.echo()
        click.echo("=" * 60)
        click.echo("  Migrate ~/.env.jira → ~/.jira/profiles.json")
        click.echo("=" * 60)
        click.echo()
        migrate_env_to_profile()
        sys.exit(EXIT_SUCCESS)

    click.echo()
    click.echo("=" * 60)
    if profile:
        click.echo(f"  Jira Profile Setup: {profile}")
    else:
        click.echo("  Jira Credential Setup")
    click.echo("=" * 60)
    click.echo()

    # For non-profile mode, check existing env file
    if not profile:
        output_path = Path(output)
        if output_path.exists() and not force and not test_only:
            click.echo(f"⚠ Configuration file already exists: {output_path}")
            if not click.confirm("Do you want to overwrite it?", default=False):
                click.echo("\nSetup cancelled.")
                sys.exit(EXIT_USER_ABORT)
            click.echo()

    # Step 1: Get Jira URL
    click.echo("Step 1: Jira Instance URL")
    click.echo("-" * 40)

    if url:
        click.echo(f"Using provided URL: {url}")
    else:
        click.echo("Enter your Jira instance URL.")
        click.echo("Examples:")
        click.echo("  - https://company.atlassian.net (Jira Cloud)")
        click.echo("  - https://jira.company.com (Jira Server/DC)")
        click.echo()
        url = click.prompt("Jira URL", type=str).strip().rstrip("/")

    # Warn about non-HTTPS URLs
    if url.startswith("http://") and not url.startswith("http://localhost"):
        warning("Using HTTP without TLS. Credentials will be transmitted in plaintext.")

    # Validate URL
    click.echo()
    click.echo("Validating URL...", nl=False)
    url_ok, url_msg = validate_url(url)
    if url_ok:
        click.echo(f" ✓ {url_msg}")
    else:
        click.echo(" ✗")
        error(f"URL validation failed: {url_msg}")
        sys.exit(EXIT_VALIDATION_FAILED)

    # Step 2: Detect/confirm Jira type
    click.echo()
    click.echo("Step 2: Authentication Type")
    click.echo("-" * 40)

    if jira_type == "auto":
        detected = detect_jira_type(url)
        click.echo(f"Detected Jira type: {detected.upper()}")

        if detected == "cloud":
            click.echo("  → Using Username + API Token authentication")
        else:
            click.echo("  → Using Personal Access Token (PAT) authentication")

        if not click.confirm("Is this correct?", default=True):
            jira_type = click.prompt("Select type", type=click.Choice(["cloud", "server"]), default=detected)
        else:
            jira_type = detected

    click.echo()

    # Step 3: Get credentials
    click.echo("Step 3: Credentials")
    click.echo("-" * 40)

    config = {"JIRA_URL": url}

    # Save the chosen type. Without it the scripts fall back to the URL, which
    # is wrong for a Cloud site behind a proxy or a custom domain, and an
    # exported JIRA_CLOUD would fill the missing key in the env file.
    is_cloud = jira_type == "cloud"
    config["JIRA_CLOUD"] = "true" if is_cloud else "false"

    if jira_type == "cloud":
        click.echo("Jira Cloud authentication requires:")
        click.echo("  1. Your Atlassian account email")
        click.echo("  2. An API token (create at https://id.atlassian.com/manage-profile/security/api-tokens)")
        click.echo()

        username = click.prompt("Email address", type=str).strip()
        api_token = click.prompt("API Token", type=str, hide_input=True).strip()

        config["JIRA_USERNAME"] = username
        config["JIRA_API_TOKEN"] = api_token

        # Validate
        click.echo()
        click.echo("Validating credentials...", nl=False)
        cred_ok, cred_msg = validate_credentials(url, "cloud", username=username, api_token=api_token)
    else:
        click.echo("Jira Server/Data Center authentication requires:")
        click.echo("  - A Personal Access Token (PAT)")
        click.echo("  - Create one in Jira: Profile → Personal Access Tokens → Create token")
        click.echo()

        personal_token = click.prompt("Personal Access Token", type=str, hide_input=True).strip()

        config["JIRA_PERSONAL_TOKEN"] = personal_token

        # Validate
        click.echo()
        click.echo("Validating credentials...", nl=False)
        cred_ok, cred_msg = validate_credentials(url, "server", personal_token=personal_token)

    if cred_ok:
        click.echo(" ✓")
        success(f"Authenticated as: {cred_msg}")
    else:
        click.echo(" ✗")
        error(f"Authentication failed: {cred_msg}")

        if jira_type == "cloud":
            click.echo()
            click.echo("Troubleshooting tips:")
            click.echo("  1. Verify your email address is correct")
            click.echo("  2. Generate a new API token at:")
            click.echo("     https://id.atlassian.com/manage-profile/security/api-tokens")
            click.echo("  3. Make sure you're using the token, not your password")
        else:
            click.echo()
            click.echo("Troubleshooting tips:")
            click.echo("  1. Create a new PAT in Jira: Profile → Personal Access Tokens")
            click.echo("  2. Ensure the token has not expired")
            click.echo("  3. Check that you have access to the Jira instance")

        sys.exit(EXIT_VALIDATION_FAILED)

    # Step 4: Save configuration
    if test_only:
        click.echo()
        click.echo("=" * 60)
        success("Credentials validated successfully!")
        click.echo("(--test-only mode: not saving to file)")
        sys.exit(EXIT_SUCCESS)

    click.echo()
    click.echo("Step 4: Save Configuration")
    click.echo("-" * 40)

    if profile:
        # Profile mode: save to ~/.jira/profiles.json
        click.echo(f"Profile '{profile}' will be saved to: {PROFILES_FILE}")
        click.echo("File permissions will be set to 600 (owner read/write only)")

        # Get project keys
        project_list = []
        if projects:
            project_list = [p.strip() for p in projects.split(",") if p.strip()]
        else:
            click.echo()
            proj_input = click.prompt(
                "Project keys (comma-separated, e.g. WEB,INFRA)", type=str, default="", show_default=False
            ).strip()
            if proj_input:
                project_list = [p.strip() for p in proj_input.split(",") if p.strip()]

        if click.confirm("Save profile?", default=True):
            profile_data = {"url": url}

            if jira_type == "cloud":
                profile_data["auth"] = "cloud"
                profile_data["username"] = config["JIRA_USERNAME"]
                profile_data["api_token"] = config["JIRA_API_TOKEN"]
            else:
                profile_data["auth"] = "pat"
                profile_data["token"] = config["JIRA_PERSONAL_TOKEN"]

            profile_data["cloud"] = is_cloud

            if project_list:
                profile_data["projects"] = project_list

            write_profile(profile, profile_data)
            click.echo()
            click.echo("=" * 60)
            success(f"Profile '{profile}' saved to {PROFILES_FILE}")
            click.echo()
            click.echo("You can now use the Jira CLI scripts:")
            click.echo(f"  uv run scripts/core/jira-validate.py --profile {profile} --verbose")
            click.echo(f"  uv run scripts/core/jira-issue.py --profile {profile} get PROJ-123")
            if project_list:
                click.echo(f"\n  Auto-resolution enabled for projects: {', '.join(project_list)}")
        else:
            click.echo("\nProfile not saved.")
            sys.exit(EXIT_USER_ABORT)
    else:
        # Legacy mode: save to env file
        output_path = Path(output)
        click.echo(f"Configuration will be saved to: {output_path}")
        click.echo("File permissions will be set to 600 (owner read/write only)")

        if click.confirm("Save configuration?", default=True):
            write_env_file(output_path, config)
            click.echo()
            click.echo("=" * 60)
            success(f"Configuration saved to {output_path}")
            click.echo()
            click.echo("You can now use the Jira CLI scripts:")
            click.echo("  uv run scripts/core/jira-validate.py --verbose")
            click.echo("  uv run scripts/core/jira-issue.py get PROJ-123")
        else:
            click.echo("\nConfiguration not saved.")
            sys.exit(EXIT_USER_ABORT)

    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