briar-cli 1.1.1__py3-none-any.whl

briar/iac/scaffold/sources/base.py

@@ -0,0 +1,61 @@
+"""SourceTemplate contract — Strategy pattern shared by every source kind.
+
+A source template knows:
+- its ``kind`` (e.g. ``"github"``, ``"jira"``, ``"aws"``)
+- its ``family`` (``"tracker"`` or ``"cloud"``) — used by the scaffold to
+  decide whether the agent should be given action tools for it
+- how to build a `Source` dict (``build_source``)
+- how to build the matching action `Tool` dicts (``build_tools``) — for a
+  cloud source this is typically empty (read-only context); for a tracker
+  it's a list of comment/transition tools
+
+Implementations live in sibling modules and self-register into
+`SOURCE_TEMPLATES` via the package `__init__`."""
+
+from __future__ import annotations
+
+import argparse
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Dict, List, Literal
+
+
+class SourceTemplate(ABC):
+    """Abstract base. Subclasses set the class attributes + implement
+    `build_source`. `build_tools` defaults to an empty list (read-only
+    source); override for trackers."""
+
+    kind: ClassVar[str] = ""
+    family: ClassVar[Literal["tracker", "cloud", ""]] = ""
+    auth_secret_arg: ClassVar[str] = ""
+    default_provider_for_oauth: ClassVar[str] = ""
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Subclasses add their own flags (e.g. `--jira-secret-id`)."""
+
+    @abstractmethod
+    def build_source(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> Dict[str, Any]:
+        """Emit the source dict the scaffold composer will include."""
+
+    def build_tools(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> List[Dict[str, Any]]:
+        """Default: source contributes no action tools. Override for
+        trackers to expose comment/transition/etc. tools."""
+        return []
+
+    def target(self, args: argparse.Namespace) -> str:
+        """Human-readable identifier for this source (e.g. ``owner/repo``).
+
+        Used by ``ScaffoldComposer`` to interpolate ``{target}`` into the
+        archetype's role/goal/backstory. The default returns ``""`` because
+        cloud sources (AWS) don't carry a single target string. Tracker
+        sources (GitHub, Bitbucket, Jira) override this to return their
+        repo / project identifier; the scaffold template picks the first
+        non-empty result among the selected sources."""
+        return ""

briar/iac/scaffold/sources/bitbucket.py

@@ -0,0 +1,164 @@
+"""Bitbucket source template.
+
+Family: `tracker`. Reads issues + pull requests from a single
+``<workspace>/<repo_slug>`` Bitbucket Cloud repository. Brings the same
+three action tools as the GitHub source — `bitbucket.comment_on_issue`,
+`bitbucket.open_pr`, `bitbucket.commit_files` — so an archetype's
+substring `tool_filter` matches on `commit`, `comment_on_issue`, and
+`open_pr` works unchanged.
+
+Auth: stored Bitbucket app-password (basic auth: username + app
+password) by default, or an OAuth connection via
+``--auth-mode oauth`` (the downstream runtime resolves the binding to
+the operator's Atlassian/Bitbucket OAuth grant).
+
+User filters (`--bitbucket-authors-allow` / `-block`,
+`--bitbucket-assignees-allow` / `-block`) restrict which issues the
+agent sees. Filters compose: ``allow ∩ ¬block``."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict, List
+
+from briar.iac.scaffold.sources.base import SourceTemplate
+
+
+class SourceBitbucket(SourceTemplate):
+    kind = "bitbucket"
+    family = "tracker"
+    default_provider_for_oauth = "bitbucket"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--bitbucket-workspace",
+            help="Bitbucket workspace slug (the part before `/` in a repo URL)",
+        )
+        parser.add_argument(
+            "--bitbucket-repo",
+            help="Bitbucket repository slug (the part after `/`)",
+        )
+        parser.add_argument(
+            "--bitbucket-secret-id",
+            help="Secret UUID holding a Bitbucket app-password " "(username + app_password stored together); required with --auth-mode pat",
+        )
+        parser.add_argument(
+            "--bitbucket-authors-allow",
+            action="append",
+            default=[],
+            help="only include issues whose reporter is in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--bitbucket-authors-block",
+            action="append",
+            default=[],
+            help="exclude issues whose reporter is in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--bitbucket-assignees-allow",
+            action="append",
+            default=[],
+            help="only include issues with an assignee in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--bitbucket-assignees-block",
+            action="append",
+            default=[],
+            help="exclude issues with an assignee in this list (repeatable)",
+        )
+
+    def build_source(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> Dict[str, Any]:
+        ns = vars(args)
+        workspace = ns.get("bitbucket_workspace")
+        repo = ns.get("bitbucket_repo")
+        if not workspace or not repo:
+            raise SystemExit("--source bitbucket requires --bitbucket-workspace AND --bitbucket-repo")
+
+        config: Dict[str, Any] = {
+            "workspace": workspace,
+            "repo": f"{workspace}/{repo}",
+            "include": "open",
+        }
+        for key, values in self._user_filters(args).items():
+            if values:
+                config[key] = values
+
+        return {
+            "key": f"{key_prefix}-bb-issues",
+            "name": f"{key_prefix}-bb-issues",
+            "kind": "bitbucket",
+            "config": config,
+            **self._auth(args),
+        }
+
+    def build_tools(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> List[Dict[str, Any]]:
+        auth = self._auth(args)
+        return [
+            {
+                "key": f"{key_prefix}-bb-comment",
+                "name": f"{key_prefix}-bb-comment",
+                "description": "Post a comment on a Bitbucket issue/PR",
+                "implementation_ref": "bitbucket.comment_on_issue",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-bb-open-pr",
+                "name": f"{key_prefix}-bb-open-pr",
+                "description": "Open a draft pull request",
+                "implementation_ref": "bitbucket.open_pr",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-bb-commit",
+                "name": f"{key_prefix}-bb-commit",
+                "description": "Commit files to a branch",
+                "implementation_ref": "bitbucket.commit_files",
+                "side_effect": "mutate",
+                **auth,
+            },
+        ]
+
+    def target(self, args: argparse.Namespace) -> str:
+        ns = vars(args)
+        workspace = ns.get("bitbucket_workspace") or ""
+        repo = ns.get("bitbucket_repo") or ""
+        if not workspace or not repo:
+            return ""
+        return f"{workspace}/{repo}"
+
+    @staticmethod
+    def _auth(args: argparse.Namespace) -> Dict[str, Any]:
+        ns = vars(args)
+        mode = ns.get("auth_mode") or "oauth"
+        if mode == "pat":
+            secret_id = ns.get("bitbucket_secret_id")
+            if not secret_id:
+                raise SystemExit("--source bitbucket with --auth-mode pat requires " "--bitbucket-secret-id <secret-uuid>")
+            return {"credentials_ref": secret_id, "credential_binding": None}
+        return {
+            "credentials_ref": None,
+            "credential_binding": {
+                "kind": "oauth_connection",
+                "provider": "bitbucket",
+            },
+        }
+
+    @staticmethod
+    def _user_filters(args: argparse.Namespace) -> Dict[str, List[str]]:
+        ns = vars(args)
+        return {
+            "authors_allow": list(ns.get("bitbucket_authors_allow") or []),
+            "authors_block": list(ns.get("bitbucket_authors_block") or []),
+            "assignees_allow": list(ns.get("bitbucket_assignees_allow") or []),
+            "assignees_block": list(ns.get("bitbucket_assignees_block") or []),
+        }

briar/iac/scaffold/sources/github.py

@@ -0,0 +1,155 @@
+"""GitHub source template.
+
+Family: `tracker`. Reads issues from `<owner>/<repo>`. Brings action
+tools for commenting on issues, opening PRs, and committing files.
+
+User filters (`--github-authors-allow`, `--github-authors-block`,
+`--github-assignees-allow`, `--github-assignees-block`) restrict which
+issues the agent sees. Filters compose: allow ∩ ¬block."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict, List
+
+from briar.iac.scaffold.sources.base import SourceTemplate
+
+
+class SourceGithub(SourceTemplate):
+    kind = "github"
+    family = "tracker"
+    default_provider_for_oauth = "github"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # Identity flags for the GitHub source. Registered here (not on
+        # the scaffold templates) so a Bitbucket-only or AWS-only scaffold
+        # doesn't have GitHub-shaped required flags. Validation that they
+        # are set happens in `build_source` when `--source github` is
+        # actually selected.
+        parser.add_argument(
+            "--owner",
+            help="GitHub org/user (required when --source includes github)",
+        )
+        parser.add_argument(
+            "--repo",
+            help="GitHub repo name (required when --source includes github)",
+        )
+        parser.add_argument(
+            "--github-authors-allow",
+            action="append",
+            default=[],
+            help="only include issues whose creator is in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--github-authors-block",
+            action="append",
+            default=[],
+            help="exclude issues whose creator is in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--github-assignees-allow",
+            action="append",
+            default=[],
+            help="only include issues with an assignee in this list (repeatable)",
+        )
+        parser.add_argument(
+            "--github-assignees-block",
+            action="append",
+            default=[],
+            help="exclude issues with an assignee in this list (repeatable)",
+        )
+
+    def build_source(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> Dict[str, Any]:
+        ns = vars(args)
+        owner = ns.get("owner")
+        repo = ns.get("repo")
+        if not owner or not repo:
+            raise SystemExit("--source github requires --owner AND --repo")
+        config: Dict[str, Any] = {
+            "owner": owner,
+            "repo": f"{owner}/{repo}",
+            "include": "open",
+        }
+        for key, values in self._user_filters(args).items():
+            if values:
+                config[key] = values
+
+        return {
+            "key": f"{key_prefix}-gh-issues",
+            "name": f"{key_prefix}-gh-issues",
+            "kind": "github",
+            "config": config,
+            **self._auth(args),
+        }
+
+    def build_tools(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> List[Dict[str, Any]]:
+        auth = self._auth(args)
+        return [
+            {
+                "key": f"{key_prefix}-gh-comment",
+                "name": f"{key_prefix}-gh-comment",
+                "description": "Post a comment on a GitHub issue/PR",
+                "implementation_ref": "github.comment_on_issue",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-gh-open-pr",
+                "name": f"{key_prefix}-gh-open-pr",
+                "description": "Open a draft pull request",
+                "implementation_ref": "github.open_pr",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-gh-commit",
+                "name": f"{key_prefix}-gh-commit",
+                "description": "Commit files to a branch",
+                "implementation_ref": "github.commit_files",
+                "side_effect": "mutate",
+                **auth,
+            },
+        ]
+
+    def target(self, args: argparse.Namespace) -> str:
+        ns = vars(args)
+        owner = ns.get("owner") or ""
+        repo = ns.get("repo") or ""
+        if not owner or not repo:
+            return ""
+        return f"{owner}/{repo}"
+
+    @staticmethod
+    def _auth(args: argparse.Namespace) -> Dict[str, Any]:
+        ns = vars(args)
+        mode = ns.get("auth_mode") or "oauth"
+        if mode == "pat":
+            secret_id = ns.get("github_secret_id")
+            if not secret_id:
+                raise SystemExit("--source github with --auth-mode pat requires " "--github-secret-id <secret-uuid>")
+            return {"credentials_ref": secret_id, "credential_binding": None}
+        return {
+            "credentials_ref": None,
+            "credential_binding": {
+                "kind": "oauth_connection",
+                "provider": "github",
+            },
+        }
+
+    @staticmethod
+    def _user_filters(args: argparse.Namespace) -> Dict[str, List[str]]:
+        ns = vars(args)
+        return {
+            "authors_allow": list(ns.get("github_authors_allow") or []),
+            "authors_block": list(ns.get("github_authors_block") or []),
+            "assignees_allow": list(ns.get("github_assignees_allow") or []),
+            "assignees_block": list(ns.get("github_assignees_block") or []),
+        }

briar/iac/scaffold/sources/jira.py

@@ -0,0 +1,147 @@
+"""Jira source template.
+
+Family: `tracker`. Reads issues from one or more Jira projects.
+Brings action tools: `jira.comment`, `jira.transition`, `jira.update_issue`.
+
+Auth: Atlassian OAuth connection by default, or a stored Atlassian PAT
+via `--jira-secret-id`."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict, List
+
+from briar.iac.scaffold.sources.base import SourceTemplate
+
+
+class SourceJira(SourceTemplate):
+    kind = "jira"
+    family = "tracker"
+    default_provider_for_oauth = "atlassian"
+
+    _FILTER_FIELDS = (
+        ("authors_allow", "jira_authors_allow"),
+        ("authors_block", "jira_authors_block"),
+        ("assignees_allow", "jira_assignees_allow"),
+        ("assignees_block", "jira_assignees_block"),
+    )
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--jira-project",
+            action="append",
+            default=[],
+            help="Jira project key to include (repeatable; defaults to all)",
+        )
+        parser.add_argument(
+            "--jira-jql",
+            help="Optional JQL filter applied on top of the project list",
+        )
+        parser.add_argument(
+            "--jira-secret-id",
+            help="Secret UUID holding an Atlassian PAT (skip OAuth)",
+        )
+        parser.add_argument(
+            "--jira-authors-allow",
+            action="append",
+            default=[],
+            help="reporter allowlist (repeatable; folds into JQL)",
+        )
+        parser.add_argument(
+            "--jira-authors-block",
+            action="append",
+            default=[],
+            help="reporter blocklist (repeatable; folds into JQL)",
+        )
+        parser.add_argument(
+            "--jira-assignees-allow",
+            action="append",
+            default=[],
+            help="assignee allowlist (repeatable; folds into JQL)",
+        )
+        parser.add_argument(
+            "--jira-assignees-block",
+            action="append",
+            default=[],
+            help="assignee blocklist (repeatable; folds into JQL)",
+        )
+
+    def build_source(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> Dict[str, Any]:
+        ns = vars(args)
+        config: Dict[str, Any] = {"include": "open"}
+        projects = ns.get("jira_project") or []
+        if projects:
+            config["projects"] = projects
+        jql = ns.get("jira_jql")
+        if jql:
+            config["jql"] = jql
+        for field, attr in self._FILTER_FIELDS:
+            values = list(ns.get(attr) or [])
+            if values:
+                config[field] = values
+
+        return {
+            "key": f"{key_prefix}-jira",
+            "name": f"{key_prefix}-jira",
+            "kind": "jira",
+            "config": config,
+            **self._auth(args),
+        }
+
+    def build_tools(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+    ) -> List[Dict[str, Any]]:
+        auth = self._auth(args)
+        return [
+            {
+                "key": f"{key_prefix}-jira-comment",
+                "name": f"{key_prefix}-jira-comment",
+                "description": "Add a comment to a Jira issue",
+                "implementation_ref": "jira.comment",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-jira-transition",
+                "name": f"{key_prefix}-jira-transition",
+                "description": "Transition a Jira issue to a new status",
+                "implementation_ref": "jira.transition",
+                "side_effect": "mutate",
+                **auth,
+            },
+            {
+                "key": f"{key_prefix}-jira-update",
+                "name": f"{key_prefix}-jira-update",
+                "description": "Update fields on a Jira issue",
+                "implementation_ref": "jira.update_issue",
+                "side_effect": "mutate",
+                **auth,
+            },
+        ]
+
+    def target(self, args: argparse.Namespace) -> str:
+        ns = vars(args)
+        projects = ns.get("jira_project") or []
+        if not projects:
+            return ""
+        return projects[0]
+
+    @staticmethod
+    def _auth(args: argparse.Namespace) -> Dict[str, Any]:
+        ns = vars(args)
+        secret_id = ns.get("jira_secret_id")
+        if secret_id:
+            return {"credentials_ref": secret_id, "credential_binding": None}
+        return {
+            "credentials_ref": None,
+            "credential_binding": {
+                "kind": "oauth_connection",
+                "provider": "atlassian",
+            },
+        }

briar/iac/scaffold/triggers/__init__.py

@@ -0,0 +1,23 @@
+"""Trigger kind registry. One file per kind; this module is the
+assembly point."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from briar._registry import build_registry
+from briar.iac.scaffold.triggers.base import TriggerTemplate
+from briar.iac.scaffold.triggers.bitbucket_webhook import TriggerBitbucketWebhook
+from briar.iac.scaffold.triggers.github_webhook import TriggerGithubWebhook
+from briar.iac.scaffold.triggers.manual import TriggerManual
+from briar.iac.scaffold.triggers.schedule_cron import TriggerScheduleCron
+
+
+TRIGGER_TEMPLATES: Dict[str, TriggerTemplate] = build_registry(
+    (TriggerGithubWebhook(), TriggerBitbucketWebhook(), TriggerScheduleCron(), TriggerManual()),
+    kind="scaffold trigger",
+    name_attr="kind",
+)
+
+
+__all__ = ["TriggerTemplate", "TRIGGER_TEMPLATES"]

briar/iac/scaffold/triggers/base.py

@@ -0,0 +1,24 @@
+"""`TriggerTemplate` contract — Strategy shared by every trigger kind."""
+
+from __future__ import annotations
+
+import argparse
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Dict
+
+
+class TriggerTemplate(ABC):
+    """Subclasses set `kind` + implement `build_trigger`.
+
+    `build_trigger` returns the trigger dict or `{}` to signal "no
+    trigger row — invocation is manual". Callers check truthiness."""
+
+    kind: ClassVar[str] = ""
+    description: ClassVar[str] = ""
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Default: no extra flags."""
+
+    @abstractmethod
+    def build_trigger(self, args: argparse.Namespace, key_prefix: str, workflow_key: str) -> Dict[str, Any]:
+        """Emit the trigger dict, or `{}` when invocation is manual."""

briar/iac/scaffold/triggers/bitbucket_webhook.py

@@ -0,0 +1,54 @@
+"""Bitbucket webhook trigger — fires on `issue:created` / `issue:updated`."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict
+
+from briar.iac.scaffold.triggers.base import TriggerTemplate
+
+
+class TriggerBitbucketWebhook(TriggerTemplate):
+    kind = "bitbucket_webhook"
+    description = "Fires on Bitbucket webhook events (issue:created, …)"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--bitbucket-webhook-events",
+            action="append",
+            default=[],
+            help="Bitbucket event names (default: issue:created, issue:updated)",
+        )
+        parser.add_argument(
+            "--bitbucket-webhook-labels",
+            action="append",
+            default=["briar"],
+            help="Restrict to issues with any of these labels (default: briar)",
+        )
+
+    def build_trigger(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+        workflow_key: str,
+    ) -> Dict[str, Any]:
+        ns = vars(args)
+        events = ns.get("bitbucket_webhook_events") or ["issue:created", "issue:updated"]
+        labels = ns.get("bitbucket_webhook_labels") or ["briar"]
+        return {
+            "key": f"{key_prefix}-trigger",
+            "name": f"{key_prefix}-trigger",
+            "kind": "bitbucket_webhook",
+            "workflow_key": workflow_key,
+            "filter_rules": {
+                "events": events,
+                "labels_any": labels,
+            },
+            "payload_to_context_mapping": {
+                "issue_number": "$.issue.id",
+                "issue_title": "$.issue.title",
+                "issue_body": "$.issue.content.raw",
+                "repo": "$.repository.full_name",
+            },
+            "is_enabled": True,
+        }

briar/iac/scaffold/triggers/github_webhook.py

@@ -0,0 +1,52 @@
+"""GitHub webhook trigger — fires on `issues.opened` / `issues.labeled`."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict
+
+from briar.iac.scaffold.triggers.base import TriggerTemplate
+
+
+class TriggerGithubWebhook(TriggerTemplate):
+    kind = "github_webhook"
+    description = "Fires on GitHub webhook events (issues.opened, …)"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--webhook-events",
+            action="append",
+            default=[],
+            help="Github event names (default: issues.opened, issues.labeled)",
+        )
+        parser.add_argument(
+            "--webhook-labels",
+            action="append",
+            default=["briar"],
+            help="Restrict to issues with any of these labels (default: briar)",
+        )
+
+    def build_trigger(
+        self,
+        args: argparse.Namespace,
+        key_prefix: str,
+        workflow_key: str,
+    ) -> Dict[str, Any]:
+        events = args.webhook_events or ["issues.opened", "issues.labeled"]
+        return {
+            "key": f"{key_prefix}-trigger",
+            "name": f"{key_prefix}-trigger",
+            "kind": "github_webhook",
+            "workflow_key": workflow_key,
+            "filter_rules": {
+                "events": events,
+                "labels_any": args.webhook_labels,
+            },
+            "payload_to_context_mapping": {
+                "issue_number": "$.issue.number",
+                "issue_title": "$.issue.title",
+                "issue_body": "$.issue.body",
+                "repo": "$.repository.full_name",
+            },
+            "is_enabled": True,
+        }