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/lib/markup_cli.py

View on GitHub
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH

"""The three markup gates every wiki-markup write goes through, as CLI helpers.

``lib/markup.py`` holds the grammar and knows nothing about the terminal;
``lib/preview.py`` asks the instance. This module is the part that talks to the
user: it repairs, it reports, and it decides when to abort. Same split as
``lib/users.py``, where ``check_mentions_cli`` wraps the mention lookup.

It exists because these three lived in ``jira-comment.py`` and therefore ran on
exactly two of the seven surfaces that post wiki markup. The other five - a
worklog comment, the comment of ``jira-transition do`` and of ``jira-transition
path``, and the description of ``jira-create issue`` and ``jira-issue update`` -
render the same markup through the same renderer and mangled it the same way.

Seven is counted from the places that POST a body. Counting the mention gate's
call sites instead gives six and misses ``jira-transition path``, which carried
neither gate.

The order is fixed and matters:

1. ``repair_markup`` escapes what can be escaped. A strikethrough span is not a
   judgement call, it is a mechanical defect with a mechanical repair.
2. ``check_markup`` reports what cannot: block tags used inline, unbalanced
   tags, and anything the escaper left behind.
3. ``check_rendering`` asks the instance, which is the only way to see what no
   source-level model can - an autolinked issue key creates a boundary that
   exists only where that key resolves.
"""

import functools
import sys
from dataclasses import dataclass, replace

import click

from lib.markup import escape_strikethrough, lint_comment_references, lint_ticket_language, lint_wiki_markup
from lib.output import error, warning
from lib.preview import preflight_render


class _Unset:
    """Sentinel for "not passed", so an explicit ``None`` stays distinguishable.

    ``render_issue_key=None`` means "render without issue context" and must not
    collapse into "fall back to ``issue_key``".
    """


_UNSET = _Unset()

# What the three gates are called on the command line. Kept here so a caller
# adding them does not invent a fourth spelling.
FORCE_HELP = "Post despite wiki-markup lint findings or a struck-through render preview"
NO_AUTO_ESCAPE_HELP = "Do not escape dashes Jira would render as strikethrough; add --force to actually post the span"
NO_PREFLIGHT_HELP = "Skip the render-preview check against the Jira instance before posting"


@dataclass(frozen=True)
class MarkupGates:
    """What the three flags decided, as one value.

    They are never meaningful apart - ``--no-auto-escape`` alone does not post
    a deliberate strikethrough, because the lint and the render check each
    refuse the surviving span - so they travel as one. The same reason
    ``guard_wiki_markup`` is a single call rather than three.
    """

    force: bool
    auto_escape: bool
    preflight: bool

    def offline(self) -> "MarkupGates":
        """The same decision with the render call dropped, for a ``--dry-run``.

        The escape and the lint still run: a preview must show the text a real
        write would post. Only the part that talks to the instance goes.
        """
        return replace(self, preflight=False)


def markup_options(func):
    """Add the three flags to a command and hand them over as one ``gates``.

    A command that writes wiki markup takes ``gates: MarkupGates`` instead of
    three booleans it would only ever pass on together. Two of three cannot be
    wired by accident, and a command does not grow three parameters per gate -
    ``jira-issue update`` crossed a 13-parameter limit when they were separate.
    """

    @functools.wraps(func)
    def wrapper(*args, force, no_auto_escape, no_preflight, **kwargs):
        kwargs["gates"] = MarkupGates(force=force, auto_escape=not no_auto_escape, preflight=not no_preflight)
        return func(*args, **kwargs)

    # functools.wraps copies __dict__, which ALIASES __click_params__ rather
    # than copying it - the three options below would be appended to the inner
    # function's list too. Harmless while each decorated function backs exactly
    # one command, and a silent way to give a second command these flags if one
    # ever did not.
    wrapper.__click_params__ = list(getattr(func, "__click_params__", []))

    # Applied bottom-up, so listing them in reverse keeps --force first in
    # --help. Asserted by test_every_surface_offers_the_three_flags.
    for option in (
        click.option("--no-preflight", is_flag=True, help=NO_PREFLIGHT_HELP),
        click.option("--no-auto-escape", is_flag=True, help=NO_AUTO_ESCAPE_HELP),
        click.option("--force", is_flag=True, help=FORCE_HELP),
    ):
        wrapper = option(wrapper)
    return wrapper


def repair_markup(text: str, auto_escape: bool, *, label: str = "text") -> str:
    """Escape dashes Jira would render as strikethrough, and say what changed.

    ``\\-`` prints as a plain hyphen, so the posted text reads exactly as
    written. Reporting the repair on stderr is deliberate - a silent rewrite of
    the user's text would be worse than the bug.

    ``--no-auto-escape`` turns it off, but not on its own: ``check_markup`` and
    ``check_rendering`` each refuse the surviving span independently, so a
    deliberate strikethrough needs ``--no-auto-escape --force``.
    """
    if not auto_escape:
        return text
    repaired = escape_strikethrough(text)
    if repaired == text:
        return text
    changed = [
        (n, after)
        for n, (before, after) in enumerate(zip(text.split("\n"), repaired.split("\n"), strict=True), 1)
        if before != after
    ]
    warning(
        f"auto-escaped {len(changed)} line(s) of the {label} that Jira would have rendered struck "
        f"through (\\- prints as a plain hyphen; use --no-auto-escape to keep the markup as written)"
    )
    for n, after in changed[:5]:
        warning(f"  line {n}: {after.strip()[:100]!r}")
    return repaired


def check_markup(text: str, force: bool, issue_key: str | None = None, *, label: str = "text") -> None:
    """Lint wiki markup, ticket language and comment references; abort on findings unless forced.

    The two kinds are labelled and explained separately: a language-only
    finding reported as a markup problem, with a suggestion about block tags,
    sends the reader looking for the wrong defect.
    """
    markup_findings = lint_wiki_markup(text)
    language_findings = lint_ticket_language(text, issue_key)
    reference_findings = lint_comment_references(text)
    if not markup_findings and not language_findings and not reference_findings:
        return

    if force:
        for finding in markup_findings:
            warning(f"markup: {finding}")
        for finding in language_findings:
            warning(f"language: {finding}")
        for finding in reference_findings:
            warning(f"reference: {finding}")
        return

    labelled = (
        [f"markup: {f}" for f in markup_findings]
        + [f"language: {f}" for f in language_findings]
        + [f"reference: {f}" for f in reference_findings]
    )
    hints = []
    if markup_findings:
        hints.append("Block tags are never inline; escape literal mentions as \\{code\\}.")
    if language_findings:
        hints.append("Re-resolve the language for this ticket; quoted user content stays verbatim.")
    if reference_findings:
        hints.append("Refer to the other comment by time, permalink, heading or timestamp, not by position.")
    hints.append("Re-run with --force to post anyway.")

    error(f"Lint found problems in the {label}:\n  " + "\n  ".join(labelled), suggestion=" ".join(hints))
    sys.exit(1)


def check_rendering(
    text: str,
    force: bool,
    issue_key: str | None,
    enabled: bool,
    env_file: str | None = None,
    profile: str | None = None,
    *,
    label: str = "text",
) -> None:
    """Ask the instance how it will render this text, and refuse a mangled write.

    The lexical repair handles what a model of the grammar CAN handle. This
    handles what it cannot, and the gap is not academic: Jira substitutes
    autolinked issue keys before text effects run, so ``OPS-899-x und zu- und``
    comes back with ``x und zu`` struck through on an instance where OPS-899
    exists and clean on one where it does not: the opener is positioned
    relative to the substituted link, not the source text. A resolved issue's
    key drawn in ``<del>`` inside its own link is status styling, and
    ``preflight_render`` does not report it.

    Advisory by construction. An unreachable, slow or absent renderer (the
    endpoint is Server/DC only) prints one warning and gets out of the way; it
    must never stop somebody writing to Jira.
    """
    if not enabled:
        return

    verdict = preflight_render(text, issue_key=issue_key, env_file=env_file, profile=profile)
    if not verdict.available:
        warning(f"render preview unavailable ({verdict.reason}) - relying on the local markup lint alone")
        return
    if not verdict.struck:
        return

    struck = "; ".join(repr(s[:80]) for s in verdict.struck[:3])
    if force:
        warning(f"rendering: Jira strikes through {struck}")
        return

    error(
        f"Jira renders part of this {label} struck through: {struck}",
        suggestion=(
            "The local escape could not fix it - this usually means an autolinked issue key "
            "(a dash right after PROJ-123) or another macro creating the boundary. Rephrase, "
            "put the token in a {code} block, or re-run with --force to write it anyway."
        ),
    )
    sys.exit(1)


def guard_wiki_markup(
    text: str,
    *,
    gates: MarkupGates,
    issue_key: str | None = None,
    render_issue_key: str | None | _Unset = _UNSET,
    env_file: str | None = None,
    profile: str | None = None,
    label: str = "text",
) -> str:
    """Run all three gates in order and return the text to write.

    One call so a caller cannot wire up two of the three and believe it is
    covered - which is how the description paths went unguarded while the
    comment path had the full treatment.

    ``render_issue_key`` exists for ``jira-create issue``, where the two gates
    need different things. The language lint only reads the project part of a
    key, so the project key alone answers it. The render endpoint resolves the
    key to an actual issue and answers 404 for a project - measured against
    jira.netresearch.de - which would print "render preview unavailable" on
    every single create. Passing ``None`` renders without issue context, which
    the endpoint accepts: the text is checked, only the autolink substitution
    that needs a surrounding issue is not.

    An absent or empty body passes straight through: ``--comment`` and
    ``--description`` are optional on most of these commands, and "nothing to
    post" is not a markup problem. Returning it unchanged also keeps None a
    None, so the caller's own "did the user supply one?" check still works.
    """
    if not text or not text.strip():
        return text
    text = repair_markup(text, gates.auto_escape, label=label)
    check_markup(text, gates.force, issue_key, label=label)
    key_for_render = issue_key if render_issue_key is _UNSET else render_issue_key
    check_rendering(text, gates.force, key_for_render, gates.preflight, env_file, profile, label=label)
    return text
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