briar-cli 1.1.1__py3-none-any.whl

briar/auth/_acquirers/jira_token.py

@@ -0,0 +1,61 @@
+"""Jira API-token acquirer.
+
+Walks the user to the Atlassian token page, then prompts for URL +
+email + paste of the generated token. Stores ``JIRA_<COMPANY>_URL``,
+``JIRA_<COMPANY>_EMAIL``, ``JIRA_<COMPANY>_TOKEN`` AND sets
+``JIRA_<COMPANY>_AUTH_KIND=token`` so ``JiraAuthRegistry.autodetect``
+always picks this strategy."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+_TOKENS_URL = "https://id.atlassian.com/manage-profile/security/api-tokens"
+
+
+class JiraTokenAcquirer(CredentialAcquirer):
+    kind = "jira-token"
+    display_name = "Jira API token (paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("jira-token: --company is required")
+
+        prompt.info("==> Jira API token")
+        prompt.info(f"    1. Open {_TOKENS_URL}")
+        prompt.info("    2. Click 'Create API token', name it `briar-<company>`")
+        prompt.info("    3. Copy the token (you only see it once)")
+        prompt.open_url(_TOKENS_URL)
+
+        url = prompt.prompt("    Jira URL (https://<org>.atlassian.net): ").strip().rstrip("/")
+        email = prompt.prompt("    Atlassian account email: ").strip()
+        token = prompt.prompt("    paste API token: ", secret=True).strip()
+        if not (url and email and token):
+            raise ValueError("jira-token: URL + email + token all required")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={
+                CredEnv.JIRA_URL.for_company(company): url,
+                CredEnv.JIRA_EMAIL.for_company(company): email,
+                CredEnv.JIRA_TOKEN.for_company(company): token,
+                CredEnv.JIRA_AUTH_KIND.for_company(company): "token",
+            },
+            metadata={"auth_mode": "api-token"},
+        )
+
+    @classmethod
+    def writes(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),
+            CredEnv.JIRA_AUTH_KIND.for_company(company),
+        ]

briar/auth/_acquirers/linear.py

@@ -0,0 +1,46 @@
+"""Linear personal API key acquirer.
+
+Walks the user to Linear settings → API → personal keys, prompts
+for the paste. Stores ``LINEAR_<COMPANY>_TOKEN``."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+_API_KEY_URL = "https://linear.app/settings/api"
+
+
+class LinearApiKeyAcquirer(CredentialAcquirer):
+    kind = "linear-api-key"
+    display_name = "Linear personal API key (paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("linear-api-key: --company is required")
+
+        prompt.info("==> Linear personal API key")
+        prompt.info(f"    1. Open {_API_KEY_URL}")
+        prompt.info("    2. Click 'New API key', name it `briar-<company>`")
+        prompt.info("    3. Copy the key (you only see it once)")
+        prompt.info("    Linear personal keys carry the user's full permissions.")
+        prompt.open_url(_API_KEY_URL)
+
+        key = prompt.prompt("    paste API key: ", secret=True).strip()
+        if not key:
+            raise ValueError("linear-api-key: empty key")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={CredEnv.LINEAR_TOKEN.for_company(company): key},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        if not company:
+            return []
+        return [CredEnv.LINEAR_TOKEN.for_company(company)]

briar/auth/_prompt.py

@@ -0,0 +1,155 @@
+"""`PromptIO` — testable abstraction for interactive terminal I/O.
+
+Every ``CredentialAcquirer`` interacts with the operator through
+exactly this surface: prompt for a paste, open a browser, poll an
+endpoint with progress. Concentrating these calls behind one
+Protocol makes acquirers fully unit-testable — the real terminal is
+swapped for a ``MockPromptIO`` that records prompts and feeds back
+scripted answers.
+
+Pattern matches what ``gh``, ``aws``, ``gcloud`` use under the hood —
+their interactive helpers all funnel through a single I/O type so
+test suites can drive every login flow without a real TTY."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable, List, Optional, Protocol, Tuple
+
+
+log = logging.getLogger(__name__)
+
+
+class PromptIO(Protocol):
+    """Terminal contract. Every acquirer's interactive surface
+    funnels through these methods — no direct ``input()`` /
+    ``getpass()`` / ``webbrowser.open`` calls anywhere else."""
+
+    def prompt(self, message: str, *, secret: bool = False) -> str:
+        """Read a single line from the user. ``secret=True`` suppresses
+        echo (passwords, tokens)."""
+        ...
+
+    def info(self, message: str) -> None:
+        """Display a single line of guidance to the operator."""
+        ...
+
+    def open_url(self, url: str) -> None:
+        """Attempt to open ``url`` in the operator's browser. Implementations
+        must degrade gracefully when no browser is available (over SSH,
+        in a container) — just log the URL so the operator can copy it."""
+        ...
+
+    def poll(
+        self,
+        *,
+        every: float,
+        max_wait: float,
+        fn: Callable[[], Optional[object]],
+        on_tick: Optional[Callable[[float], None]] = None,
+    ) -> object:
+        """Repeatedly invoke ``fn``. Return the first non-None / non-
+        empty return value. Raise ``TimeoutError`` after ``max_wait``
+        seconds. Used by OAuth device flows that poll a token endpoint."""
+        ...
+
+
+class TerminalPromptIO:
+    """Real terminal implementation — wraps ``input`` / ``getpass`` /
+    ``webbrowser.open`` / ``time.sleep``."""
+
+    def prompt(self, message: str, *, secret: bool = False) -> str:
+        if secret:
+            import getpass
+
+            return getpass.getpass(message)
+        return input(message)
+
+    def info(self, message: str) -> None:
+        print(message)
+
+    def open_url(self, url: str) -> None:
+        """Try webbrowser.open; on failure (headless / SSH) just print
+        the URL. The acquirer's narrative will already have told the
+        operator to visit it manually."""
+        try:
+            import webbrowser
+
+            opened = webbrowser.open(url, new=2)
+        except Exception:  # noqa: BLE001
+            opened = False
+        if not opened:
+            print(f"  open in your browser: {url}")
+
+    def poll(
+        self,
+        *,
+        every: float,
+        max_wait: float,
+        fn: Callable[[], Optional[object]],
+        on_tick: Optional[Callable[[float], None]] = None,
+    ) -> object:
+        deadline = time.monotonic() + max_wait
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"PromptIO.poll: gave up after {max_wait}s")
+            try:
+                result = fn()
+            except Exception:  # noqa: BLE001 — pollers handle their own retry shape
+                result = None
+            if result:
+                return result
+            if on_tick is not None:
+                on_tick(remaining)
+            time.sleep(min(every, remaining))
+
+
+class MockPromptIO:
+    """Scripted PromptIO for tests. Each ``answer`` is consumed by
+    the next ``prompt`` call. ``info`` / ``open_url`` are recorded
+    but otherwise ignored. ``poll`` invokes ``fn`` up to
+    ``poll_attempts`` times — useful for testing device-flow polling
+    without real sleeps."""
+
+    def __init__(
+        self,
+        *,
+        answers: Optional[List[str]] = None,
+        poll_attempts: int = 1,
+    ) -> None:
+        self._answers: List[str] = list(answers or [])
+        self._poll_attempts = poll_attempts
+        self.info_log: List[str] = []
+        self.opened_urls: List[str] = []
+        self.prompts: List[Tuple[str, bool]] = []
+
+    def prompt(self, message: str, *, secret: bool = False) -> str:
+        self.prompts.append((message, secret))
+        if not self._answers:
+            raise AssertionError(f"MockPromptIO: no scripted answer for prompt {message!r}")
+        return self._answers.pop(0)
+
+    def info(self, message: str) -> None:
+        self.info_log.append(message)
+
+    def open_url(self, url: str) -> None:
+        self.opened_urls.append(url)
+
+    def poll(
+        self,
+        *,
+        every: float,
+        max_wait: float,
+        fn: Callable[[], Optional[object]],
+        on_tick: Optional[Callable[[float], None]] = None,
+    ) -> object:
+        for _ in range(self._poll_attempts):
+            result = fn()
+            if result:
+                return result
+        raise TimeoutError(f"MockPromptIO.poll: exhausted {self._poll_attempts} attempts")
+
+
+__all__ = ["MockPromptIO", "PromptIO", "TerminalPromptIO"]

briar/cli.py

@@ -0,0 +1,149 @@
+"""Top-level entry point.
+
+`Cli.main` is the actual program. The module-level `main()` is a thin
+shim retained because the console-script declared in pyproject.toml
+binds to it — moving the binding would break installed shells."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from typing import Dict, List, Set, Tuple
+
+from briar.commands import Command, build_registry
+from briar.errors import CliError
+from briar.formatting import FORMATTERS
+from briar.logging import configure as configure_logging, env_verbose
+
+
+# Two flag families:
+#   GLOBAL_FLAGS_WITH_VALUE: `--format yaml` / `--format=yaml`
+#   GLOBAL_BOOL_FLAGS:       `--verbose` / `-v` (no value)
+_GLOBAL_FLAGS_WITH_VALUE: Set[str] = {"--format"}
+_GLOBAL_BOOL_FLAGS: Set[str] = {"--verbose", "-v"}
+
+
+class Cli:
+    """Argparse driver. Static-only — no instance state."""
+
+    @classmethod
+    def main(cls, argv: List[str] = []) -> int:
+        raw_argv = list(argv) if argv else sys.argv[1:]
+        try:
+            kv, flags, remaining = cls._extract_global_flags(raw_argv)
+        except CliError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+
+        # Configure logging before anything else so module imports that
+        # log at import-time still inherit the right level.
+        verbose = "--verbose" in flags or "-v" in flags or env_verbose()
+        configure_logging(verbose=verbose)
+        log = logging.getLogger("briar.cli")
+        log.debug("argv=%r verbose=%s", raw_argv, verbose)
+
+        # Bootstrap credentials from any configured remote vault BEFORE
+        # the command registry imports (which transitively trigger
+        # provider / writer adapter construction that may read env vars
+        # at import time). auto_bootstrap() iterates the BOOTSTRAPS
+        # registry — typically a no-op locally, runs InfisicalBootstrap
+        # on hosts that have the universal-auth machine identity set.
+        from briar.credentials._bootstraps import auto_bootstrap
+
+        result = auto_bootstrap()
+        if not result.ok:
+            log.warning("credential-bootstrap: %s failed — %s", result.backend, result.error)
+        elif result.count:
+            log.info("credential-bootstrap: %s hydrated %d env vars", result.backend, result.count)
+
+        commands = build_registry()
+        parser = cls._build_parser(commands)
+
+        normalised: List[str] = []
+        for flag, value in kv.items():
+            normalised.extend([flag, value])
+        normalised.extend(remaining)
+
+        args = parser.parse_args(normalised)
+        log.debug("dispatching command=%s args=%r", args.command, vars(args))
+
+        try:
+            return commands[args.command].run(args)
+        except CliError as exc:
+            log.error("command %s failed: %s", args.command, exc)
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        except KeyboardInterrupt:
+            log.warning("interrupted by user (KeyboardInterrupt)")
+            print("\ninterrupted", file=sys.stderr)
+            return 130
+        except Exception:  # noqa: BLE001 — top-level catch-all logs the trace
+            log.exception("command %s crashed unexpectedly", args.command)
+            return 2
+
+    @classmethod
+    def _extract_global_flags(cls, argv: List[str]) -> Tuple[Dict[str, str], Set[str], List[str]]:
+        """Pull global flags out of argv regardless of position. Handles
+        `--flag value`, `--flag=value`, and bare boolean flags."""
+        extracted: Dict[str, str] = {}
+        bool_flags: Set[str] = set()
+        rest: List[str] = []
+        i = 0
+        while i < len(argv):
+            token = argv[i]
+            if token in _GLOBAL_BOOL_FLAGS:
+                bool_flags.add(token)
+                i += 1
+                continue
+            if token in _GLOBAL_FLAGS_WITH_VALUE:
+                if i + 1 >= len(argv):
+                    raise CliError(f"{token} requires a value")
+                extracted[token] = argv[i + 1]
+                i += 2
+                continue
+            matched_equals = False
+            for flag in _GLOBAL_FLAGS_WITH_VALUE:
+                prefix = f"{flag}="
+                if token.startswith(prefix):
+                    extracted[flag] = token[len(prefix) :]
+                    matched_equals = True
+                    break
+            if matched_equals:
+                i += 1
+                continue
+            rest.append(token)
+            i += 1
+        return extracted, bool_flags, rest
+
+    @staticmethod
+    def _build_parser(commands: Dict[str, Command]) -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser(
+            prog="briar",
+            description="Local extraction + scaffolding tool. No remote calls to Briar.",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        parser.add_argument(
+            "--format",
+            choices=list(FORMATTERS.keys()),
+            default="table",
+            help="output format (default: table for lists, json for single records)",
+        )
+        # `--verbose` is consumed in `_extract_global_flags`, but declare
+        # it here too so `briar --help` mentions it.
+        parser.add_argument(
+            "--verbose",
+            "-v",
+            action="store_true",
+            help="enable DEBUG-level logging (also honours BRIAR_VERBOSE=1 env var)",
+        )
+        sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+        for name, cmd in commands.items():
+            sp = sub.add_parser(name, help=cmd.help)
+            cmd.add_arguments(sp)
+        return parser
+
+
+# Console-script entry point declared in pyproject.toml.
+def main(argv: List[str] = []) -> int:
+    return Cli.main(argv)

briar/commands/__init__.py

@@ -0,0 +1,48 @@
+"""Command registry — Strategy + Factory composition.
+
+After the API-removal cut, the surface is five commands:
+  extract  · runbook  · scaffold  · context  · version
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Type
+
+from briar.commands.agent import CommandAgent
+from briar.commands.auth import CommandAuth
+from briar.commands.base import Command, confirm
+from briar.commands.context import ContextCommand
+from briar.commands.dashboard import CommandDashboard
+from briar.commands.extract import CommandExtract
+from briar.commands.iac import CommandScaffold
+from briar.commands.runbook import CommandRunbook
+from briar.commands.secrets import CommandSecrets
+from briar.commands.version import CommandVersion
+
+
+class CommandRegistry:
+    """Resolves the {name → Command} map. Static-only — no instance
+    state, no mutation after import time."""
+
+    COMMANDS: List[Type[Command]] = [
+        CommandExtract,
+        CommandRunbook,
+        CommandScaffold,
+        ContextCommand,
+        CommandDashboard,
+        CommandAgent,
+        CommandAuth,
+        CommandSecrets,
+        CommandVersion,
+    ]
+
+    @classmethod
+    def build(cls) -> Dict[str, Command]:
+        return {cls_.name: cls_() for cls_ in cls.COMMANDS}
+
+
+# Back-compat shim — `build_registry()` was the previous public name.
+build_registry = CommandRegistry.build
+
+
+__all__ = ["Command", "CommandRegistry", "build_registry", "confirm"]