briar-cli 1.1.1__py3-none-any.whl

briar/iac/scaffold/triggers/manual.py

@@ -0,0 +1,16 @@
+"""Manual trigger — no trigger row; invocation is via `briar tasks create`."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict
+
+from briar.iac.scaffold.triggers.base import TriggerTemplate
+
+
+class TriggerManual(TriggerTemplate):
+    kind = "manual"
+    description = "No trigger row; invoke via `briar tasks create`"
+
+    def build_trigger(self, args: argparse.Namespace, key_prefix: str, workflow_key: str) -> Dict[str, Any]:
+        return {}

briar/iac/scaffold/triggers/schedule_cron.py

@@ -0,0 +1,37 @@
+"""Cron-schedule trigger — fires the workflow on a cron expression."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict
+
+from briar.iac.scaffold.triggers.base import TriggerTemplate
+
+
+class TriggerScheduleCron(TriggerTemplate):
+    kind = "schedule_cron"
+    description = "Fires on a cron schedule (default: hourly)"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--schedule",
+            default="0 * * * *",
+            help="cron expression (default: '0 * * * *' = top of every hour)",
+        )
+
+    def build_trigger(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+        workflow_key: str,
+    ) -> Dict[str, Any]:
+        return {
+            "key": f"{key_prefix}-cron",
+            "name": f"{key_prefix}-cron",
+            "kind": "schedule",
+            "workflow_key": workflow_key,
+            "schedule_cron": args.schedule,
+            "filter_rules": {},
+            "payload_to_context_mapping": {},
+            "is_enabled": True,
+        }

briar/log_context.py

@@ -0,0 +1,73 @@
+"""Context-aware logging — stamps every log record in the active
+context with the (company, task, extractor, ...) breadcrumb.
+
+Usage:
+
+    from briar.log_context import log_context
+
+    with log_context(company="acme", task="prfix"):
+        log.info("starting cycle")            # → "[acme/prfix] starting cycle"
+        with log_context(extractor="active-work"):
+            log.info("fetching repos")        # → "[acme/prfix/active-work] fetching repos"
+
+The implementation uses a `contextvars.ContextVar` so it is async-safe
+and thread-safe, plus a `logging.Filter` that turns the active mapping
+into a `[k=v k=v]` prefix on the `message`. We rewrite the message
+instead of relying on an `extra=` slot so the prefix shows up in every
+formatter without requiring per-format changes."""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import logging
+from typing import Any, Dict, Iterator
+
+
+_CTX: contextvars.ContextVar[Dict[str, str]] = contextvars.ContextVar("briar_log_ctx", default={})
+
+
+@contextlib.contextmanager
+def log_context(**bindings: Any) -> Iterator[None]:
+    """Push key=value pairs onto the active log context for the
+    duration of the `with` block. Nested calls extend (not replace)
+    the parent context."""
+    current = dict(_CTX.get())
+    for key, value in bindings.items():
+        current[key] = str(value)
+    token = _CTX.set(current)
+    try:
+        yield
+    finally:
+        _CTX.reset(token)
+
+
+def current_context() -> Dict[str, str]:
+    """Read-only snapshot of the active bindings. Useful for callers
+    that want to ferry breadcrumbs into structured payloads, not just
+    log lines."""
+    return dict(_CTX.get())
+
+
+class ContextFilter(logging.Filter):
+    """Filter that prepends `[k1=v1 k2=v2]` to every log record's
+    message when the context has bindings. Attached to the root logger
+    by `briar.logging.configure`."""
+
+    _ORDER = ("company", "task", "extractor", "shape", "repo")
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        ctx = _CTX.get()
+        if not ctx:
+            return True
+        ordered: list = []
+        for key in self._ORDER:
+            value = ctx.get(key)
+            if value:
+                ordered.append(f"{key}={value}")
+        for key, value in ctx.items():
+            if key not in self._ORDER:
+                ordered.append(f"{key}={value}")
+        prefix = "[" + " ".join(ordered) + "] "
+        record.msg = prefix + str(record.msg)
+        return True

briar/logging.py

@@ -0,0 +1,68 @@
+"""Logging configuration — one place to set the format, level, and
+output stream so every module can `logging.getLogger(__name__)` and
+get consistent output across the CLI, scheduler, and dashboard.
+
+Output shape (line-prefix):
+    2026-05-20T15:32:19Z [INFO   ] briar.iac.runbook.scheduler: …
+
+Always UTC. Always to stdout (so the existing `nohup` redirects on
+the droplet capture into `scheduler.log` / `dashboard.log`). Errors
+caught in broad-except sites should call `logger.exception(...)`,
+which appends the traceback automatically."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+
+
+_FORMAT = "%(asctime)s [%(levelname)-7s] %(name)s: %(message)s"
+_DATEFMT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def configure(verbose: bool = False) -> None:
+    """Configure root logger. INFO by default; `--verbose` → DEBUG.
+
+    Force-reconfigures even if `logging.basicConfig` ran already, so
+    test imports + repeated CLI invocations stay deterministic.
+    Also attaches a `ContextFilter` so anything pushed onto
+    `briar.log_context.log_context` gets prepended to every record."""
+    from briar.log_context import ContextFilter
+
+    level = logging.DEBUG if verbose else logging.INFO
+    # `force=True` removes any pre-existing handlers so a test that
+    # imported briar before configuring doesn't double-log.
+    logging.basicConfig(
+        level=level,
+        format=_FORMAT,
+        datefmt=_DATEFMT,
+        stream=sys.stdout,
+        force=True,
+    )
+    # Always log in UTC.
+    logging.Formatter.converter = time.gmtime
+    # Attach the context filter to every existing handler. New handlers
+    # added later (e.g. by tests) will not get it automatically; that is
+    # intentional — production never adds handlers after configure().
+    context_filter = ContextFilter()
+    for handler in logging.getLogger().handlers:
+        handler.addFilter(context_filter)
+    # Quiet noisy third-party libs regardless of --verbose. The flag is
+    # meant to turn up briar's own DEBUG output, not bury us in every
+    # TLS handshake. Use BRIAR_LIB_DEBUG=1 to flip these on.
+    if not _lib_debug_enabled():
+        for noisy in ("httpx", "httpcore", "urllib3", "schedule", "boto3", "botocore"):
+            logging.getLogger(noisy).setLevel(logging.WARNING)
+    logging.captureWarnings(True)
+
+
+def _lib_debug_enabled() -> bool:
+    return os.environ.get("BRIAR_LIB_DEBUG", "").strip().lower() in {"1", "true", "yes"}
+
+
+def env_verbose() -> bool:
+    """`BRIAR_VERBOSE=1` flips DEBUG for daemonised invocations where
+    no `--verbose` flag is being passed (the dashboard / serve units)."""
+    return os.environ.get("BRIAR_VERBOSE", "").strip().lower() in {"1", "true", "yes"}

briar/messaging/__init__.py

@@ -0,0 +1,66 @@
+"""Message-writer registry — Strategy + Factory.
+
+Each writer wraps one vendor's outbound write API. Adding a new
+vendor (Discord, Linear-comment, GitLab-MR-comment, …) = one module
++ one entry in the `(WriterClass, ...)` tuple here.
+
+The factory `make_writer(kind, company, config)` is what `SendMessageTool`
+calls at run time. Each runbook company's ``messages:`` block names
+bindings by handle; the tool resolves handle → kind → factory."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple, Type
+
+from briar._registry import build_registry
+from briar.errors import CliError
+from briar.messaging._writer import MessageBindingResolved, MessageWriter, SendResult
+from briar.messaging.bitbucket_pr_comment import BitbucketPrCommentWriter
+from briar.messaging.github_pr_comment import GithubPrCommentWriter
+from briar.messaging.jira_comment import JiraCommentWriter
+from briar.messaging.jira_transition import JiraTransitionWriter
+from briar.messaging.slack_channel import SlackChannelWriter
+from briar.messaging.telegram_chat import TelegramChatWriter
+
+
+WRITERS: Dict[str, Type[MessageWriter]] = build_registry(
+    (
+        JiraCommentWriter,
+        JiraTransitionWriter,
+        SlackChannelWriter,
+        TelegramChatWriter,
+        GithubPrCommentWriter,
+        BitbucketPrCommentWriter,
+    ),
+    kind="message writer",
+    name_attr="kind",
+)
+
+
+class MessageWriterRegistry:
+    """Factory + introspection."""
+
+    @classmethod
+    def kinds(cls) -> Tuple[str, ...]:
+        return tuple(WRITERS.keys())
+
+    @classmethod
+    def make(cls, kind: str, *, company: str = "", config: Dict[str, Any] = None) -> MessageWriter:
+        writer_cls = WRITERS.get(kind)
+        if writer_cls is None:
+            known = ", ".join(sorted(WRITERS.keys()))
+            raise CliError(f"unknown message writer {kind!r}; known: {known}")
+        return writer_cls(company=company, config=config or {})
+
+
+make_writer = MessageWriterRegistry.make
+
+
+__all__ = [
+    "WRITERS",
+    "MessageWriter",
+    "MessageWriterRegistry",
+    "MessageBindingResolved",
+    "SendResult",
+    "make_writer",
+]

briar/messaging/_writer.py

@@ -0,0 +1,90 @@
+"""`MessageWriter` — vendor-neutral write surface.
+
+Symmetric to `TrackerProvider` / `RepositoryProvider` but for outbound
+writes instead of reads. Each adapter wraps one vendor's write API
+(Jira comment, Slack channel post, Telegram chat message, …).
+
+Strategy + Registry. Adapters live in `messaging/` siblings; the
+`WRITERS` registry is built via `build_registry()` so a duplicate
+`kind` collision raises at import time.
+
+Two consumers today:
+- `briar agent` invokes writers via the `SendMessageTool` (the LLM
+  picks a configured channel by name; the tool resolves the channel
+  to a writer + calls `send`).
+- Future scheduler hooks (deferred) — extract-success notifications,
+  status broadcasts.
+
+Each runbook company can declare named writer bindings under
+``messages:`` (see `iac/runbook/models.py:MessageBinding`); the
+agent picks them up via the company-scoped config injected at run
+time."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Dict, List
+
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SendResult:
+    """Outcome of one write. `ok=False` is logged but does NOT raise —
+    same fire-and-forget semantics as `NotificationSink.send`.
+    Caller branches on `ok` for retries / chained behaviour."""
+
+    ok: bool
+    detail: str = ""
+    ref: str = ""  # provider-side message id when known (Jira comment id, Slack ts, …)
+
+
+class MessageWriter(ABC):
+    """Strategy contract for one vendor's outbound write."""
+
+    kind: ClassVar[str] = ""
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True iff the writer has the credentials it needs (env vars
+        + any binding-level config) to perform a real send."""
+
+    @abstractmethod
+    def send(self, *, target: str, body: str, **extras: Any) -> SendResult:
+        """Send `body` to `target`. `target` is vendor-specific:
+
+        - Jira-comment:   ``PROJ-123`` (ticket key)
+        - Jira-transition: ``PROJ-123`` (ticket key) + ``extras["status"]=...``
+        - Slack-channel:  the channel is per-binding config (the
+                          target arg can override with a different
+                          channel ID at send time)
+        - Telegram-chat:  the chat is per-binding config (same)
+        - GH/BB PR comment: ``owner/repo#42`` + optional inline
+                          ``extras["file_path"]`` + ``extras["line"]``
+
+        Implementations should not raise on transient network errors —
+        return ``SendResult(ok=False, detail="...")`` and let the
+        caller decide on retry."""
+
+    @classmethod
+    def required_env_vars(cls, company: str = "") -> List[str]:
+        """Same contract as `RepositoryProvider.required_env_vars` —
+        env-var names this writer needs. Empty default (writers that
+        configure entirely via the runbook binding's `config` dict
+        don't need env vars)."""
+        return []
+
+
+@dataclass(frozen=True)
+class MessageBindingResolved:
+    """A runbook ``messages:`` entry post-resolution. The runbook YAML
+    holds `kind` + freeform `config`; this is the typed version that
+    the agent tool + scheduler hooks see."""
+
+    handle: str  # the YAML key (e.g. "ticket_comment", "ops_chat")
+    kind: str  # registered writer kind
+    company: str
+    config: Dict[str, Any] = field(default_factory=dict)

briar/messaging/bitbucket_pr_comment.py

@@ -0,0 +1,93 @@
+"""Bitbucket Cloud PR-comment writer.
+
+Top-level OR inline (with `extras["file_path"]`). `target` is
+``workspace/repo#42``. Uses the same atlassian-python-api Cloud
+client + per-company `BITBUCKET_<COMPANY>_*` creds as
+`BitbucketProvider`."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Tuple
+
+from briar.decorators import swallow_errors
+from briar.env_vars import CredEnv
+from briar.messaging._writer import MessageWriter, SendResult
+
+
+log = logging.getLogger(__name__)
+
+
+class BitbucketPrCommentWriter(MessageWriter):
+    kind = "bitbucket-pr-comment"
+    BASE = "https://api.bitbucket.org/"
+
+    def __init__(self, *, company: str = "", config: Dict[str, Any] = None) -> None:
+        self._company = company
+        self._config = config or {}
+        self._username = CredEnv.BITBUCKET_USERNAME.read(company=company) if company else ""
+        self._app_password = CredEnv.BITBUCKET_APP_PASSWORD.read(company=company) if company else ""
+        self._workspace_slug = CredEnv.BITBUCKET_WORKSPACE.read(company=company) if company else ""
+        self._client = None
+
+    def _cloud(self):
+        if self._client is None:
+            from atlassian.bitbucket.cloud import Cloud
+
+            if self._username == "x-token-auth":
+                self._client = Cloud(url=self.BASE, token=self._app_password)
+            else:
+                self._client = Cloud(url=self.BASE, username=self._username, password=self._app_password)
+        return self._client
+
+    def is_available(self) -> bool:
+        return bool(self._username and self._app_password and self._workspace_slug)
+
+    @swallow_errors(default=SendResult(ok=False, detail="exception"), message="bitbucket-pr-comment send")
+    def send(self, *, target: str, body: str, **extras: Any) -> SendResult:
+        repo_addr, number = self._parse_target(target, extras)
+        if not repo_addr or not number:
+            return SendResult(ok=False, detail=f"bitbucket-pr-comment requires target=workspace/repo#N; got {target!r}")
+        workspace_slug, _, repo_slug = repo_addr.partition("/")
+        if not workspace_slug or not repo_slug:
+            workspace_slug = self._workspace_slug
+            repo_slug = repo_addr
+        bb_repo = self._cloud().workspaces.get(workspace_slug).repositories.get(repo_slug)
+
+        # PR comment payload — inline if file_path + line are set
+        payload: Dict[str, Any] = {"content": {"raw": body}}
+        file_path = extras.get("file_path")
+        if file_path:
+            payload["inline"] = {
+                "path": file_path,
+                "to": int(extras.get("line") or 1),
+            }
+        resp = bb_repo.post(f"pullrequests/{number}/comments", data=payload)
+        comment_id = str((resp or {}).get("id") or "") if isinstance(resp, dict) else ""
+        return SendResult(ok=True, ref=comment_id)
+
+    @staticmethod
+    def _parse_target(target: str, extras: Dict[str, Any]) -> Tuple[str, int]:
+        if "#" in target:
+            addr, _, n = target.rpartition("#")
+            try:
+                return addr, int(n)
+            except ValueError:
+                return "", 0
+        n_extras = extras.get("pr")
+        if target and n_extras is not None:
+            try:
+                return target, int(n_extras)
+            except (TypeError, ValueError):
+                return "", 0
+        return "", 0
+
+    @classmethod
+    def required_env_vars(cls, company: str = "") -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.BITBUCKET_USERNAME.for_company(company),
+            CredEnv.BITBUCKET_APP_PASSWORD.for_company(company),
+            CredEnv.BITBUCKET_WORKSPACE.for_company(company),
+        ]

briar/messaging/github_pr_comment.py

@@ -0,0 +1,90 @@
+"""GitHub PR-comment writer.
+
+Posts either:
+- a TOP-LEVEL issue/PR comment (default), or
+- an INLINE review-thread reply when ``extras["file_path"]`` is set.
+
+``target`` is ``owner/repo#42`` (the #42 is the PR number). The PR
+number can also be passed as ``extras["pr"]`` if the target is a
+bare repo slug.
+
+Backed by the same `GithubApi` PyGithub facade the reads use."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Tuple
+
+from briar.decorators import swallow_errors
+from briar.extract._gh import GithubApi
+from briar.messaging._writer import MessageWriter, SendResult
+
+
+log = logging.getLogger(__name__)
+
+
+class GithubPrCommentWriter(MessageWriter):
+    kind = "github-pr-comment"
+
+    def __init__(self, *, company: str = "", config: Dict[str, Any] = None) -> None:
+        # GITHUB_TOKEN is workspace-wide; company is inert.
+        self._company = company
+        self._config = config or {}
+
+    def is_available(self) -> bool:
+        return bool(GithubApi.auth_token())
+
+    @swallow_errors(default=SendResult(ok=False, detail="exception"), message="github-pr-comment send")
+    def send(self, *, target: str, body: str, **extras: Any) -> SendResult:
+        repo, number = self._parse_target(target, extras)
+        if not repo or not number:
+            return SendResult(ok=False, detail=f"github-pr-comment requires target=owner/repo#N; got {target!r}")
+
+        file_path = extras.get("file_path")
+        if file_path:
+            # Inline review-thread reply requires the PR's head SHA +
+            # a file/line anchor. The replies endpoint uses commit_id.
+            pr = GithubApi.get_json(f"/repos/{repo}/pulls/{number}")
+            commit_id = ((pr or {}).get("head") or {}).get("sha") or ""
+            if not commit_id:
+                return SendResult(ok=False, detail="github-pr-comment inline: could not resolve head SHA")
+            line = int(extras.get("line") or 0)
+            payload = {
+                "body": body,
+                "commit_id": commit_id,
+                "path": file_path,
+                "line": line or 1,
+                "side": extras.get("side", "RIGHT"),
+            }
+            client = GithubApi.client()
+            headers, resp = client._Github__requester.requestJsonAndCheck("POST", f"/repos/{repo}/pulls/{number}/comments", input=payload)
+            comment_id = str((resp or {}).get("id") or "") if isinstance(resp, dict) else ""
+            return SendResult(ok=True, ref=comment_id)
+
+        # Top-level issue comment endpoint (the same one GitHub uses
+        # for non-inline PR comments).
+        client = GithubApi.client()
+        headers, resp = client._Github__requester.requestJsonAndCheck("POST", f"/repos/{repo}/issues/{number}/comments", input={"body": body})
+        comment_id = str((resp or {}).get("id") or "") if isinstance(resp, dict) else ""
+        return SendResult(ok=True, ref=comment_id)
+
+    @staticmethod
+    def _parse_target(target: str, extras: Dict[str, Any]) -> Tuple[str, int]:
+        """Accept `owner/repo#42` OR bare `owner/repo` + `extras["pr"]`."""
+        if "#" in target:
+            repo, _, n = target.rpartition("#")
+            try:
+                return repo, int(n)
+            except ValueError:
+                return "", 0
+        n_extras = extras.get("pr")
+        if target and n_extras is not None:
+            try:
+                return target, int(n_extras)
+            except (TypeError, ValueError):
+                return "", 0
+        return "", 0
+
+    @classmethod
+    def required_env_vars(cls, company: str = "") -> List[str]:
+        return ["GITHUB_TOKEN"]

briar/messaging/jira_comment.py

@@ -0,0 +1,63 @@
+"""Jira ticket-comment writer.
+
+Adds a comment to a Jira ticket. Backed by the same
+``atlassian-python-api`` Jira client that `JiraTracker` uses for
+reads, so creds are the per-company JIRA_<COMPANY>_{URL,EMAIL,TOKEN}
+already documented in `CredEnv`."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from briar.decorators import swallow_errors
+from briar.env_vars import CredEnv
+from briar.messaging._writer import MessageWriter, SendResult
+
+
+log = logging.getLogger(__name__)
+
+
+class JiraCommentWriter(MessageWriter):
+    kind = "jira-comment"
+
+    def __init__(self, *, company: str = "", config: Dict[str, Any] = None) -> None:
+        self._company = company
+        self._config = config or {}
+        self._url = CredEnv.JIRA_URL.read(company=company) if company else ""
+        self._email = CredEnv.JIRA_EMAIL.read(company=company) if company else ""
+        self._token = CredEnv.JIRA_TOKEN.read(company=company) if company else ""
+        self._client = None
+
+    def _jira(self):
+        if self._client is None:
+            from atlassian import Jira
+
+            self._client = Jira(url=self._url, username=self._email, password=self._token, cloud=True)
+        return self._client
+
+    def is_available(self) -> bool:
+        return bool(self._url and self._email and self._token)
+
+    @swallow_errors(default=SendResult(ok=False, detail="exception"), message="jira-comment send")
+    def send(self, *, target: str, body: str, **extras: Any) -> SendResult:
+        if not self.is_available():
+            return SendResult(ok=False, detail="jira creds missing")
+        if not target:
+            return SendResult(ok=False, detail="jira-comment requires target=<TICKET-KEY>")
+        # atlassian-python-api: client.issue_add_comment(issue_key, comment)
+        resp = self._jira().issue_add_comment(target, body)
+        if not isinstance(resp, dict):
+            return SendResult(ok=False, detail=f"jira returned non-dict: {resp!r}")
+        comment_id = str(resp.get("id") or "")
+        return SendResult(ok=True, ref=comment_id)
+
+    @classmethod
+    def required_env_vars(cls, company: str = "") -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.JIRA_URL.for_company(company),
+            CredEnv.JIRA_EMAIL.for_company(company),
+            CredEnv.JIRA_TOKEN.for_company(company),
+        ]

briar/messaging/jira_transition.py

@@ -0,0 +1,71 @@
+"""Jira ticket-transition writer.
+
+Transitions a Jira ticket to a target status. The status name comes
+either from ``extras["status"]`` at send time or from the binding's
+``config: {status: "Done"}`` default.
+
+`body` is recorded as an optional resolution comment (Jira's
+transitions can carry a comment field)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+
+from briar.decorators import swallow_errors
+from briar.env_vars import CredEnv
+from briar.messaging._writer import MessageWriter, SendResult
+
+
+log = logging.getLogger(__name__)
+
+
+class JiraTransitionWriter(MessageWriter):
+    kind = "jira-transition"
+
+    def __init__(self, *, company: str = "", config: Dict[str, Any] = None) -> None:
+        self._company = company
+        self._config = config or {}
+        self._default_status = str(self._config.get("status", ""))
+        self._url = CredEnv.JIRA_URL.read(company=company) if company else ""
+        self._email = CredEnv.JIRA_EMAIL.read(company=company) if company else ""
+        self._token = CredEnv.JIRA_TOKEN.read(company=company) if company else ""
+        self._client = None
+
+    def _jira(self):
+        if self._client is None:
+            from atlassian import Jira
+
+            self._client = Jira(url=self._url, username=self._email, password=self._token, cloud=True)
+        return self._client
+
+    def is_available(self) -> bool:
+        return bool(self._url and self._email and self._token)
+
+    @swallow_errors(default=SendResult(ok=False, detail="exception"), message="jira-transition send")
+    def send(self, *, target: str, body: str, **extras: Any) -> SendResult:
+        if not self.is_available():
+            return SendResult(ok=False, detail="jira creds missing")
+        if not target:
+            return SendResult(ok=False, detail="jira-transition requires target=<TICKET-KEY>")
+        status = extras.get("status") or self._default_status
+        if not status:
+            return SendResult(ok=False, detail="jira-transition requires extras.status or binding config.status")
+        # The library exposes `set_issue_status` which wraps the
+        # /transitions endpoint + the transition-id resolution.
+        # `body` is appended as a comment via `comment=` when supplied.
+        result = self._jira().set_issue_status(target, status, comment=body or None)
+        if result is None:
+            return SendResult(ok=True, ref=f"{target}→{status}")
+        # Atlassian's response shape varies — treat any non-None as ok.
+        return SendResult(ok=True, ref=str(result)[:200])
+
+    @classmethod
+    def required_env_vars(cls, company: str = "") -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.JIRA_URL.for_company(company),
+            CredEnv.JIRA_EMAIL.for_company(company),
+            CredEnv.JIRA_TOKEN.for_company(company),
+        ]