imbi-plugin-sentry 2.46.0__py3-none-any.whl

imbi/plugins/sentry/__init__.py

@@ -0,0 +1,9 @@
+from importlib import metadata
+
+from imbi.plugins.sentry.plugin import SentryPlugin
+
+#: Discovered by the imbi-common registry's convention scan.
+PLUGIN = SentryPlugin
+
+version = metadata.version('imbi-plugin-sentry')
+__all__ = ['PLUGIN', 'SentryPlugin', 'version']

imbi/plugins/sentry/actions.py

@@ -0,0 +1,90 @@
+"""Webhook action: sync the project's Sentry issue-count facts."""
+
+import logging
+import typing
+import urllib.parse
+
+import pydantic
+import pydantic_settings
+
+from imbi.common.api import client as api_client
+from imbi.common.plugins import base as plugin_base
+from imbi.plugins.sentry import client
+
+LOGGER = logging.getLogger(__name__)
+
+
+class _ImbiSettings(pydantic_settings.BaseSettings):
+    """Imbi API connection settings, the same environment variables the
+    gateway's own actions read (see the SonarQube plugin)."""
+
+    model_config = {'env_prefix': 'IMBI_GATEWAY_'}
+
+    imbi_url: pydantic.HttpUrl = pydantic.Field(
+        default=pydantic.HttpUrl('http://localhost:8000'),
+        validation_alias='IMBI_INTERNAL_API_URL',
+    )
+    # imbi-api mounts its routers under the path of its public URL.
+    api_public_url: str = pydantic.Field(
+        default='', validation_alias='IMBI_API_URL'
+    )
+    api_token: str
+
+    @property
+    def api_base_url(self) -> str:
+        prefix = urllib.parse.urlparse(self.api_public_url).path.rstrip('/')
+        return str(self.imbi_url).rstrip('/') + prefix
+
+
+class SyncIssueCountsConfig(pydantic.BaseModel):
+    """No settings: the facts and searches are Integration options."""
+
+
+async def sync_issue_counts(
+    *,
+    ctx: plugin_base.PluginContext,
+    credentials: dict[str, str],
+    external_identifier: str,
+    action_config: SyncIssueCountsConfig,
+    event: object,
+) -> None:
+    """Re-count the project's Sentry issues and patch the facts.
+
+    ``external_identifier`` is the Sentry project slug the gateway
+    matched against ``EXISTS_IN.identifier``. The count is read from
+    Sentry, not derived from the event, so a missed delivery cannot make
+    the fact drift.
+    """
+    del action_config, event
+    try:
+        s = client.settings(ctx, credentials)
+        project = await client.get_project(s, external_identifier)
+        if project is None:
+            LOGGER.warning(
+                'Sentry project %r not found; skipping', external_identifier
+            )
+            return
+        counts = await client.count_all(ctx, s, project)
+    except client.SentryClientError:
+        LOGGER.exception(
+            'Failed to count Sentry issues for %r', external_identifier
+        )
+        return
+    await _patch_imbi_project(
+        ctx.org_slug,
+        ctx.project_id,
+        [
+            {'op': 'add', 'path': f'/{fact}', 'value': count}
+            for fact, count in counts.items()
+        ],
+    )
+
+
+async def _patch_imbi_project(
+    org_slug: str, project_id: str, patch: list[dict[str, typing.Any]]
+) -> None:
+    settings = _ImbiSettings()  # type: ignore[call-arg]
+    async with api_client.Imbi(
+        base_url=settings.api_base_url, token=settings.api_token, timeout=30.0
+    ) as imbi:
+        await imbi.patch_project(org_slug, project_id, patch)

imbi/plugins/sentry/client.py

@@ -0,0 +1,298 @@
+"""Sentry REST API client, plus the settings every capability shares."""
+
+import asyncio
+import importlib.metadata
+import re
+import typing
+import urllib.parse
+
+import httpx
+
+from imbi.common.plugins.base import PluginContext, ServiceWriteback
+
+_VERSION = importlib.metadata.version('imbi-plugin-sentry')
+
+#: Project link key the issues URL is written under.
+LINK_KEY = 'sentry'
+
+#: Fact name -> Sentry issue search, when the operator sets none.
+DEFAULT_ISSUE_COUNT_FACTS = {'sentry_open_issues': 'is:unresolved'}
+
+#: Issue search window, when the operator sets none. Sentry's issue
+#: stream defaults to the same window, so the linked page shows the
+#: issues that were counted.
+DEFAULT_ISSUE_PERIOD = '14d'
+
+
+class SentryClientError(Exception):
+    """Raised on non-2xx responses or transport errors."""
+
+
+_SLUG_RE = re.compile(r'[A-Za-z0-9_-]+')
+
+
+class Settings(typing.NamedTuple):
+    """What every Sentry call needs, resolved from the Integration."""
+
+    base_url: str
+    organization: str
+    auth_token: str
+
+
+def settings(ctx: PluginContext, credentials: dict[str, str]) -> Settings:
+    """Resolve the Integration settings, or raise :class:`SentryClientError`.
+
+    The message is the one the operator sees, so it names what to set.
+    """
+    base_url = str(ctx.integration_options.get('service_url') or '').strip()
+    organization = str(
+        ctx.integration_options.get('organization') or ''
+    ).strip()
+    auth_token = credentials.get('auth_token', '')
+    if not organization:
+        raise SentryClientError('The Integration has no organization set.')
+    if not auth_token:
+        raise SentryClientError('No auth_token credential configured.')
+    return Settings(
+        (base_url or 'https://sentry.io').rstrip('/'), organization, auth_token
+    )
+
+
+def _mapping(ctx: PluginContext, name: str) -> dict[str, str]:
+    """Return the ``mapping`` option ``name`` as ``dict[str, str]``."""
+    raw: object = ctx.integration_options.get(name)
+    if not isinstance(raw, dict):
+        return {}
+    items = typing.cast('dict[object, object]', raw).items()
+    return {str(k): str(v) for k, v in items}
+
+
+def issue_count_facts(ctx: PluginContext) -> dict[str, str]:
+    """Return the configured ``fact name -> Sentry issue search`` map."""
+    return _mapping(ctx, 'issue_count_facts') or dict(
+        DEFAULT_ISSUE_COUNT_FACTS
+    )
+
+
+def issue_period(ctx: PluginContext) -> str:
+    raw = str(ctx.integration_options.get('issue_period') or '').strip()
+    return raw or DEFAULT_ISSUE_PERIOD
+
+
+def sentry_team(ctx: PluginContext) -> str | None:
+    """Return the Sentry team that owns the project's Sentry project.
+
+    The ``team_mapping`` option wins; an unmapped team uses its own slug.
+    """
+    if ctx.team_slug is None:
+        return None
+    return _mapping(ctx, 'team_mapping').get(ctx.team_slug) or ctx.team_slug
+
+
+def writeback(
+    ctx: PluginContext, s: Settings, project: dict[str, typing.Any]
+) -> ServiceWriteback:
+    """Build the ``EXISTS_IN`` edge + issues link for a Sentry project."""
+    slug = str(project['slug'])
+    query = urllib.parse.urlencode(
+        {'project': project['id'], 'statsPeriod': issue_period(ctx)}
+    )
+    return ServiceWriteback(
+        identifier=slug,
+        canonical_url=canonical_url(s, slug),
+        dashboard_links={
+            LINK_KEY: (
+                f'{s.base_url}/organizations/{s.organization}/issues/?{query}'
+            )
+        },
+    )
+
+
+def _q(segment: str) -> str:
+    """Return a Sentry slug for a URL path, or raise.
+
+    Sentry slugs hold only letters, digits, ``-`` and ``_``. Anything
+    else (``..``, ``/``, encoded forms of either) could point a call at a
+    different API path, because httpx normalizes the path.
+    """
+    if not _SLUG_RE.fullmatch(segment):
+        raise SentryClientError(f'{segment!r} is not a valid Sentry slug')
+    return segment
+
+
+def canonical_url(s: Settings, slug: str) -> str:
+    return f'{s.base_url}/api/0/projects/{_q(s.organization)}/{_q(slug)}/'
+
+
+async def _request(
+    s: Settings,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, str] | None = None,
+    json: dict[str, typing.Any] | None = None,
+) -> httpx.Response:
+    headers = {
+        'Authorization': f'Bearer {s.auth_token}',
+        'Accept': 'application/json',
+        'User-Agent': f'imbi-plugin-sentry/{_VERSION}',
+    }
+    try:
+        # Within the host's default 10 second plugin deadline.
+        async with httpx.AsyncClient(timeout=10.0) as http_client:
+            return await http_client.request(
+                method,
+                f'{s.base_url}/api/0{path}',
+                params=params,
+                json=json,
+                headers=headers,
+            )
+    except httpx.RequestError as exc:
+        raise SentryClientError(f'Sentry request failed: {exc}') from exc
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    if response.is_error:
+        raise SentryClientError(
+            f'Sentry returned status {response.status_code}: '
+            f'{response.text[:200]}'
+        )
+
+
+def _json(response: httpx.Response) -> dict[str, typing.Any]:
+    _raise_for_error(response)
+    try:
+        payload: object = response.json()
+    except ValueError as exc:
+        raise SentryClientError('Sentry returned non-JSON response') from exc
+    if not isinstance(payload, dict):
+        raise SentryClientError('Sentry returned an unexpected payload')
+    return typing.cast('dict[str, typing.Any]', payload)
+
+
+async def get_project(s: Settings, slug: str) -> dict[str, typing.Any] | None:
+    """Return the Sentry project ``slug``, or ``None`` when it is absent."""
+    response = await _request(
+        s, 'GET', f'/projects/{_q(s.organization)}/{_q(slug)}/'
+    )
+    if response.status_code == 404:
+        return None
+    return _json(response)
+
+
+async def create_project(
+    s: Settings, team: str, slug: str, name: str
+) -> dict[str, typing.Any]:
+    """Create a Sentry project owned by ``team``.
+
+    Sentry answers ``404`` when the team does not exist.
+    """
+    response = await _request(
+        s,
+        'POST',
+        f'/teams/{_q(s.organization)}/{_q(team)}/projects/',
+        json={'name': name, 'slug': slug},
+    )
+    if response.status_code == 404:
+        raise SentryClientError(
+            f'Sentry team {team!r} does not exist; map the Imbi team to a '
+            'Sentry team in the team_mapping option.'
+        )
+    return _json(response)
+
+
+def team_slugs(project: dict[str, typing.Any]) -> list[str]:
+    """Return the slugs of the teams that own a Sentry project."""
+    teams: object = project.get('teams') or []
+    if not isinstance(teams, list):
+        return []
+    return [
+        str(typing.cast('dict[str, typing.Any]', t).get('slug'))
+        for t in typing.cast('list[object]', teams)
+        if isinstance(t, dict)
+    ]
+
+
+def may_link(project: dict[str, typing.Any], team: str | None) -> bool:
+    """Return whether Imbi may link an existing Sentry project.
+
+    Only when no team owns it, or ``team`` already does: linking a
+    project owned only by other teams would hand it to this project.
+    """
+    current = team_slugs(project)
+    return not current or team in current
+
+
+async def set_team(
+    s: Settings, project: dict[str, typing.Any], team: str
+) -> list[str]:
+    """Make ``team`` the only team that owns ``project``.
+
+    Removes other teams only when ``team`` already owns the project, so
+    someone with access in Sentry has granted it; a project with no team
+    gets ``team`` added. Otherwise raises, because replacing the owners
+    of a project that ``team`` has no claim to would take it from them.
+    Returns the removed team slugs.
+    """
+    slug = str(project['slug'])
+    path = f'/projects/{_q(s.organization)}/{_q(slug)}/teams'
+    current = team_slugs(project)
+    if current and team not in current:
+        raise SentryClientError(
+            f'Sentry team {team!r} does not own this project; add it to the '
+            'project in Sentry first.'
+        )
+    if not current:
+        response = await _request(s, 'POST', f'{path}/{_q(team)}/')
+        if response.status_code == 404:
+            raise SentryClientError(
+                f'Sentry team {team!r} does not exist; map the Imbi team to '
+                'a Sentry team in the team_mapping option.'
+            )
+        _raise_for_error(response)
+    removed = [t for t in current if t != team]
+    for other in removed:
+        _raise_for_error(await _request(s, 'DELETE', f'{path}/{_q(other)}/'))
+    return removed
+
+
+async def count_issues(
+    s: Settings, project_id: str, query: str, period: str
+) -> int:
+    """Count the project's issues that match ``query`` in ``period``.
+
+    Reads the ``X-Hits`` header of the organization issues endpoint.
+    """
+    # ponytail: X-Hits is approximate and caps at 1000; paginate the
+    # issue list if a fact needs an exact count past that.
+    response = await _request(
+        s,
+        'GET',
+        f'/organizations/{_q(s.organization)}/issues/',
+        params={
+            'project': project_id,
+            'query': query,
+            'statsPeriod': period,
+            'limit': '1',
+        },
+    )
+    _raise_for_error(response)
+    hits = response.headers.get('X-Hits')
+    if hits is None or not hits.isdigit():
+        raise SentryClientError('Sentry returned no X-Hits issue count')
+    return int(hits)
+
+
+async def count_all(
+    ctx: PluginContext, s: Settings, project: dict[str, typing.Any]
+) -> dict[str, int]:
+    """Return ``{fact name: issue count}`` for every configured fact."""
+    period = issue_period(ctx)
+    facts = issue_count_facts(ctx)
+    counts = await asyncio.gather(
+        *(
+            count_issues(s, str(project['id']), query, period)
+            for query in facts.values()
+        )
+    )
+    return dict(zip(facts, counts, strict=True))

imbi/plugins/sentry/doctor.py

@@ -0,0 +1,383 @@
+"""Sentry project doctor.
+
+Checks that the project's ``EXISTS_IN`` edge names a live Sentry project
+and that the edge and the ``sentry`` issues link match it, offering to
+create or link the project. Then compares each configured issue-count
+fact against Sentry and offers a sweepable sync.
+
+Diagnosis is best-effort: missing configuration or an unreachable Sentry
+degrades to ``warn`` findings, so the Doctor panel never hard-fails.
+"""
+
+from __future__ import annotations
+
+import typing
+
+from imbi.common.plugins.base import (
+    AnalysisCapability,
+    AnalysisResultItem,
+    AnalysisResultStatus,
+    PluginContext,
+    RemediationOffer,
+    RemediationResult,
+    ServiceConnection,
+)
+from imbi.plugins.sentry import client
+from imbi.plugins.sentry.lifecycle import find_or_create
+
+#: Search Sentry for the project, create it when absent, write the edge.
+_CREATE = 'create-project'
+#: Rewrite the edge + link for a project analyze() found. Never creates.
+_LINK = 'link-project'
+#: Write the issue-count facts.
+_SYNC_FACTS = 'sync-issue-counts'
+#: Make the expected team the only owner of the Sentry project.
+_SET_TEAM = 'set-team'
+
+_CREATE_OFFER = RemediationOffer(
+    id=_CREATE,
+    label='Create / link the Sentry project',
+    confirm=(
+        'This creates the Sentry project if it does not exist, then links '
+        'it to this project.'
+    ),
+    destructive=True,
+)
+_SET_TEAM_OFFER = RemediationOffer(
+    id=_SET_TEAM,
+    label='Set the Sentry team',
+    confirm=(
+        'This makes the expected team the only owner of the Sentry project. '
+        'Every other team loses its access to the project.'
+    ),
+    destructive=True,
+)
+_LINK_OFFER = RemediationOffer(id=_LINK, label='Repair the Sentry link')
+_SYNC_OFFER = RemediationOffer(
+    id=_SYNC_FACTS, label='Sync issue counts from Sentry', sweepable=True
+)
+
+
+def _item(
+    slug: str,
+    title: str,
+    status: AnalysisResultStatus,
+    description: str,
+    remediation: RemediationOffer | None = None,
+) -> AnalysisResultItem:
+    return AnalysisResultItem(
+        slug=slug,
+        title=title,
+        status=status,
+        description=description,
+        remediation=remediation,
+    )
+
+
+def _connection(ctx: PluginContext) -> ServiceConnection | None:
+    return next(
+        (
+            c
+            for c in ctx.service_connections
+            if c.integration_slug == ctx.integration_slug
+        ),
+        None,
+    )
+
+
+def _slug(ctx: PluginContext) -> str:
+    """The edge's identifier wins over the project-slug convention."""
+    connection = _connection(ctx)
+    return connection.identifier if connection else ctx.project_slug
+
+
+def _count_matches(value: object, count: int) -> bool:
+    """Return whether a stored fact equals a Sentry count.
+
+    A bool is an int in Python, so ``True == 1``; reject it explicitly.
+    """
+    return type(value) is int and value == count
+
+
+def _may_link(ctx: PluginContext, project: dict[str, typing.Any]) -> bool:
+    """Return whether the Doctor may link ``project`` to this project.
+
+    An existing edge is kept: someone already chose it. A new link follows
+    the rule of :func:`find_or_create`.
+    """
+    return _connection(ctx) is not None or client.may_link(
+        project, client.sentry_team(ctx)
+    )
+
+
+def _owns_sentry_project(ctx: PluginContext) -> bool:
+    """Return whether the project may change its Sentry project's teams.
+
+    Only for the Sentry project named after this project, through an edge
+    the plugin wrote itself (or no edge yet). An identifier set by hand
+    could name another team's Sentry project, and replacing its teams
+    would take that project away from them.
+    """
+    connection = _connection(ctx)
+    if connection is not None and (
+        connection.verified_identifier != connection.identifier
+    ):
+        return False
+    return _slug(ctx) == ctx.project_slug
+
+
+class SentryDoctor(AnalysisCapability):
+    """Validate and repair the project's Sentry project binding."""
+
+    async def analyze(
+        self, ctx: PluginContext, credentials: dict[str, str]
+    ) -> list[AnalysisResultItem]:
+        if not ctx.integration_slug:
+            return [
+                _item(
+                    'exists-in',
+                    'Sentry project',
+                    'warn',
+                    'This capability is not bound to an Integration.',
+                )
+            ]
+        slug = _slug(ctx)
+        try:
+            s = client.settings(ctx, credentials)
+            project = await client.get_project(s, slug)
+        except client.SentryClientError as exc:
+            return [
+                _item(
+                    'exists-in',
+                    'Sentry project',
+                    'warn',
+                    f'Cannot verify Sentry project {slug!r}: {exc}',
+                )
+            ]
+        if project is None:
+            return [
+                _item(
+                    'exists-in',
+                    'Sentry project',
+                    'fail',
+                    f'Sentry project {slug!r} does not exist. Use the Fix '
+                    'action to create and link it.',
+                    _CREATE_OFFER,
+                )
+            ]
+        return [
+            self._check_link(ctx, s, project),
+            self._check_team(ctx, project),
+            *await self._check_facts(ctx, s, project),
+        ]
+
+    def _check_link(
+        self,
+        ctx: PluginContext,
+        s: client.Settings,
+        project: dict[str, typing.Any],
+    ) -> AnalysisResultItem:
+        expected = client.writeback(ctx, s, project)
+        connection = _connection(ctx)
+        if (
+            connection is not None
+            and connection.identifier == expected.identifier
+            and connection.canonical_url == expected.canonical_url
+            and ctx.project_links.get(client.LINK_KEY)
+            == expected.dashboard_links[client.LINK_KEY]
+        ):
+            return _item(
+                'exists-in',
+                'Sentry project',
+                'pass',
+                f'Linked to Sentry project {expected.identifier!r}.',
+            )
+        if not _may_link(ctx, project):
+            return _item(
+                'exists-in',
+                'Sentry project',
+                'fail',
+                f'Sentry project {expected.identifier!r} is owned only by '
+                f'other teams ({", ".join(client.team_slugs(project))}); '
+                'Imbi cannot link it. Add the mapped team to it in Sentry, '
+                'then re-run the doctor.',
+            )
+        return _item(
+            'exists-in',
+            'Sentry project',
+            'warn' if connection is None else 'fail',
+            f'Sentry project {expected.identifier!r} exists, but the '
+            'project edge or issues link does not match it. Use the Fix '
+            'action to link it.',
+            _LINK_OFFER,
+        )
+
+    def _check_team(
+        self, ctx: PluginContext, project: dict[str, typing.Any]
+    ) -> AnalysisResultItem:
+        expected = client.sentry_team(ctx)
+        teams = client.team_slugs(project)
+        if expected is None:
+            return _item(
+                'sentry-team',
+                'Sentry team',
+                'warn',
+                'The project has no owning team to map to a Sentry team.',
+            )
+        if teams == [expected]:
+            return _item(
+                'sentry-team',
+                'Sentry team',
+                'pass',
+                f'Sentry team {expected!r} owns the project.',
+            )
+        if not _owns_sentry_project(ctx) or not client.may_link(
+            project, expected
+        ):
+            return _item(
+                'sentry-team',
+                'Sentry team',
+                'fail',
+                f'The Sentry project is owned by {teams or "no team"}; '
+                f'expected only {expected!r}. Imbi cannot claim this Sentry '
+                f'project; add {expected!r} to it in Sentry, then re-run the '
+                'doctor.',
+            )
+        return _item(
+            'sentry-team',
+            'Sentry team',
+            'fail',
+            f'The Sentry project is owned by {teams or "no team"}; expected '
+            f'only {expected!r}. Use the Fix action to set the team.',
+            _SET_TEAM_OFFER,
+        )
+
+    async def _check_facts(
+        self,
+        ctx: PluginContext,
+        s: client.Settings,
+        project: dict[str, typing.Any],
+    ) -> list[AnalysisResultItem]:
+        try:
+            counts = await client.count_all(ctx, s, project)
+        except client.SentryClientError as exc:
+            return [
+                _item(
+                    'issue-counts',
+                    'Sentry issue counts',
+                    'warn',
+                    f'Cannot count Sentry issues: {exc}',
+                )
+            ]
+        return [
+            _item(
+                f'issue-count:{fact}',
+                f'Fact {fact}',
+                'pass',
+                f'{fact} matches Sentry ({count}).',
+            )
+            if _count_matches(ctx.project_facts.get(fact), count)
+            else _item(
+                f'issue-count:{fact}',
+                f'Fact {fact}',
+                'warn',
+                f'{fact} is {ctx.project_facts.get(fact)!r}; Sentry reports '
+                f'{count}.',
+                _SYNC_OFFER,
+            )
+            for fact, count in counts.items()
+        ]
+
+    async def remediate(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        remediation_id: str,
+    ) -> RemediationResult:
+        if remediation_id not in (_CREATE, _LINK, _SYNC_FACTS, _SET_TEAM):
+            return await super().remediate(ctx, credentials, remediation_id)
+        slug = _slug(ctx)
+        try:
+            s = client.settings(ctx, credentials)
+            project: dict[str, typing.Any] | None
+            if remediation_id == _CREATE:
+                project, created = await find_or_create(ctx, s, slug)
+            else:
+                project, created = await client.get_project(s, slug), False
+            if project is None:
+                return RemediationResult(
+                    status='failed',
+                    message=(
+                        f'Sentry project {slug!r} no longer exists; '
+                        're-run the doctor to create it.'
+                    ),
+                )
+            if remediation_id == _LINK and not _may_link(ctx, project):
+                return RemediationResult(
+                    status='failed',
+                    message=(
+                        f'Sentry project {slug!r} is owned only by other '
+                        'teams; refusing to link it.'
+                    ),
+                )
+            if remediation_id == _SYNC_FACTS:
+                return await self._sync_facts(ctx, s, project)
+            if remediation_id == _SET_TEAM:
+                return await self._set_team(ctx, s, project)
+        except client.SentryClientError as exc:
+            return RemediationResult(status='failed', message=str(exc))
+        ctx.service_writeback = client.writeback(ctx, s, project)
+        verb = 'Created and linked' if created else 'Linked'
+        return RemediationResult(
+            status='fixed', message=f'{verb} Sentry project {slug!r}.'
+        )
+
+    async def _sync_facts(
+        self,
+        ctx: PluginContext,
+        s: client.Settings,
+        project: dict[str, typing.Any],
+    ) -> RemediationResult:
+        counts = await client.count_all(ctx, s, project)
+        if all(
+            _count_matches(ctx.project_facts.get(f), c)
+            for f, c in counts.items()
+        ):
+            return RemediationResult(
+                status='noop', message='Issue counts already match Sentry.'
+            )
+        ctx.fact_writeback = dict[str, typing.Any](counts)
+        return RemediationResult(
+            status='fixed',
+            message=', '.join(f'{f} = {c}' for f, c in counts.items()),
+        )
+
+    async def _set_team(
+        self,
+        ctx: PluginContext,
+        s: client.Settings,
+        project: dict[str, typing.Any],
+    ) -> RemediationResult:
+        if not _owns_sentry_project(ctx):
+            return RemediationResult(
+                status='failed',
+                message=(
+                    'Imbi did not link this Sentry project itself; change '
+                    'its teams in Sentry.'
+                ),
+            )
+        team = client.sentry_team(ctx)
+        if team is None:
+            return RemediationResult(
+                status='failed',
+                message='The project has no owning team to map.',
+            )
+        if client.team_slugs(project) == [team]:
+            return RemediationResult(
+                status='noop', message=f'Sentry team {team!r} already set.'
+            )
+        removed = await client.set_team(s, project, team)
+        suffix = f'; removed {", ".join(removed)}' if removed else ''
+        return RemediationResult(
+            status='fixed', message=f'Set Sentry team {team!r}{suffix}.'
+        )

imbi/plugins/sentry/lifecycle.py

@@ -0,0 +1,74 @@
+"""Sentry lifecycle capability: create the Sentry project with the Imbi one.
+
+The Sentry project slug is the Imbi project slug and is written to the
+``EXISTS_IN`` edge, so the gateway routes Sentry webhooks to the
+project. There is no delete hook: deleting the Imbi project drops its
+edge and links, and the Sentry project keeps its issue history.
+"""
+
+from __future__ import annotations
+
+import typing
+
+from imbi.common.plugins.base import (
+    LifecycleCapability,
+    LifecycleResult,
+    PluginContext,
+)
+from imbi.plugins.sentry import client
+
+
+async def find_or_create(
+    ctx: PluginContext, s: client.Settings, slug: str
+) -> tuple[dict[str, typing.Any], bool]:
+    """Return the Sentry project ``slug`` and whether it was created.
+
+    Raises :class:`client.SentryClientError` when it is absent and cannot
+    be created.
+    """
+    project = await client.get_project(s, slug)
+    team = client.sentry_team(ctx)
+    if project is not None:
+        if not client.may_link(project, team):
+            raise client.SentryClientError(
+                f'Sentry project {slug!r} exists and is owned only by other '
+                f'teams ({", ".join(client.team_slugs(project))}); refusing '
+                'to link it.'
+            )
+        return project, False
+    if team is None:
+        raise client.SentryClientError(
+            'The project has no owning team to map to a Sentry team.'
+        )
+    project = await client.create_project(
+        s, team, slug, ctx.project_name or slug
+    )
+    return project, True
+
+
+class SentryLifecycle(LifecycleCapability):
+    """Create (or link) the project's Sentry project."""
+
+    async def on_project_archived(
+        self, ctx: PluginContext, credentials: dict[str, str]
+    ) -> LifecycleResult:
+        del ctx, credentials
+        return LifecycleResult(
+            status='skipped', message='Sentry has no archive concept'
+        )
+
+    async def on_project_created(
+        self, ctx: PluginContext, credentials: dict[str, str]
+    ) -> LifecycleResult:
+        try:
+            s = client.settings(ctx, credentials)
+            project, created = await find_or_create(ctx, s, ctx.project_slug)
+        except client.SentryClientError as exc:
+            return LifecycleResult(status='failed', message=str(exc))
+        ctx.service_writeback = client.writeback(ctx, s, project)
+        verb = 'Created' if created else 'Linked existing'
+        return LifecycleResult(
+            status='ok',
+            message=f'{verb} Sentry project {project["slug"]!r}',
+            artifacts={'project_id': str(project['id'])},
+        )

imbi/plugins/sentry/plugin.py

@@ -0,0 +1,148 @@
+"""Sentry plugin (Plugin Architecture v3)."""
+
+from imbi.common import plugins
+from imbi.common.plugins.base import WebhookSignature
+from imbi.plugins.sentry import client
+from imbi.plugins.sentry.doctor import SentryDoctor
+from imbi.plugins.sentry.lifecycle import SentryLifecycle
+
+
+class SentryWebhookActions(plugins.WebhookActionsCapability):
+    """Sentry integration-platform webhooks, routed by project slug."""
+
+    @classmethod
+    def actions(cls) -> list[plugins.ActionDescriptor]:
+        return [
+            plugins.ActionDescriptor.model_validate(
+                {
+                    'name': 'sync_issue_counts',
+                    'label': 'Sync Sentry issue counts',
+                    'description': (
+                        'Counts the Sentry issues that match each search in '
+                        'the issue_count_facts option and patches the '
+                        'matching project facts.'
+                    ),
+                    'callable': (
+                        'imbi.plugins.sentry.actions:sync_issue_counts'
+                    ),
+                    'config_model': (
+                        'imbi.plugins.sentry.actions:SyncIssueCountsConfig'
+                    ),
+                }
+            )
+        ]
+
+    @classmethod
+    def signature(cls) -> WebhookSignature:
+        # Hex HMAC-SHA256 of the raw body, keyed by the Sentry internal
+        # integration's client secret, with no prefix.
+        return WebhookSignature(
+            header='sentry-hook-signature', prefix='', secret='webhook'
+        )
+
+
+class SentryPlugin(plugins.Plugin):
+    """Sentry integration plugin."""
+
+    manifest = plugins.PluginManifest.model_validate(
+        {
+            'slug': 'sentry',
+            'name': 'Sentry',
+            'icon': 'si-sentry',
+            'description': (
+                'Create and link a Sentry project for each project, and keep '
+                'issue-count facts in sync from Sentry webhooks and the '
+                'Project Doctor.'
+            ),
+            'auth_type': 'api_token',
+            'options': [
+                {
+                    'name': 'service_url',
+                    'label': 'Sentry URL',
+                    'description': (
+                        'Base URL of Sentry. Leave blank for '
+                        'https://sentry.io.'
+                    ),
+                    'type': 'string',
+                },
+                {
+                    'name': 'organization',
+                    'label': 'Sentry organization slug',
+                    'type': 'string',
+                    'required': True,
+                },
+                {
+                    'name': 'team_mapping',
+                    'label': 'Team to Sentry team',
+                    'description': (
+                        'Maps an Imbi team slug to the Sentry team that owns '
+                        "the team's new Sentry projects. An unmapped team "
+                        'uses its own slug.'
+                    ),
+                    'type': 'mapping',
+                },
+                {
+                    'name': 'issue_count_facts',
+                    'label': 'Issue-count facts',
+                    'description': (
+                        'Maps a project fact name to the Sentry issue search '
+                        'whose count it holds, e.g. `sentry_open_issues` to '
+                        '`is:unresolved`. Each fact must exist as an integer '
+                        'property in a project blueprint.'
+                    ),
+                    'type': 'mapping',
+                    'default': client.DEFAULT_ISSUE_COUNT_FACTS,
+                },
+                {
+                    'name': 'issue_period',
+                    'label': 'Issue search period',
+                    'description': (
+                        'Sentry statsPeriod the counts cover, e.g. `14d` or '
+                        '`90d`. The issues link uses the same period.'
+                    ),
+                    'type': 'string',
+                    'default': client.DEFAULT_ISSUE_PERIOD,
+                },
+            ],
+            'credentials': [
+                {
+                    'name': 'auth_token',
+                    'label': 'Sentry auth token',
+                    'description': (
+                        'Token of a Sentry internal integration with '
+                        'Project: Admin (to create projects) and Issue & '
+                        'Event: Read.'
+                    ),
+                }
+            ],
+            'capabilities': [
+                {
+                    'kind': 'lifecycle',
+                    'label': 'Project lifecycle',
+                    'description': (
+                        'Create (or link) a Sentry project when a project '
+                        'is created.'
+                    ),
+                    'hints': {'lifecycle_events': ['created']},
+                    'handler': SentryLifecycle,
+                },
+                {
+                    'kind': 'webhook-actions',
+                    'label': 'Webhook actions',
+                    'description': (
+                        'Sentry issue webhooks dispatched by imbi-gateway.'
+                    ),
+                    'handler': SentryWebhookActions,
+                },
+                {
+                    'kind': 'analysis',
+                    'label': 'Project doctor',
+                    'description': (
+                        'Validate the Sentry project link and issue-count '
+                        'facts against Sentry, with one-click repairs.'
+                    ),
+                    'handler': SentryDoctor,
+                },
+            ],
+        }
+    )

imbi_plugin_sentry-2.46.0.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: imbi-plugin-sentry
+Version: 2.46.0
+Summary: Sentry integration plugin for Imbi
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: imbi-common==2.46.0
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# imbi-plugin-sentry
+
+Sentry integration plugin for Imbi (Plugin Architecture v3). See
+[the plugin documentation](https://aweber-imbi.github.io/imbi/plugins/sentry/).

imbi_plugin_sentry-2.46.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+imbi/plugins/sentry/__init__.py,sha256=rzDIHWTGzQiLLlbfkY5s4vkDZ3hvO-bwVz27hOqd524,266
+imbi/plugins/sentry/actions.py,sha256=oGY2X-6xTu0pu3FPLU5PyoPxu4l4pFeCTGChHyby8_w,2853
+imbi/plugins/sentry/client.py,sha256=hrYS09QyRGj5qVeW812wzjarShvYIDvbhDcXgWZ7CBo,9850
+imbi/plugins/sentry/doctor.py,sha256=KfLwb0BzK6fZXUVgZ23xVrJ8mDSA6b1B2cZRhM1r6EA,13097
+imbi/plugins/sentry/lifecycle.py,sha256=ZyKo8O118vXMmv_DoySvZyhSQ76nKDa3MQVqaQ30xaM,2602
+imbi/plugins/sentry/plugin.py,sha256=fI37un9evaRUOIdbsqF-5mAF4oxFrEIBV_pf6mt7Ens,5700
+imbi/plugins/sentry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imbi_plugin_sentry-2.46.0.dist-info/METADATA,sha256=IFEQ2jpOxrp9OU1iz6kXCsSrulQrgxPsH6BIc6R2lCI,783
+imbi_plugin_sentry-2.46.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+imbi_plugin_sentry-2.46.0.dist-info/RECORD,,

imbi_plugin_sentry-2.46.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any