briar-cli 1.1.1__py3-none-any.whl

briar/commands/runbook.py

@@ -0,0 +1,110 @@
+"""`briar runbook` — multi-company knowledge extraction from YAML.
+
+Subcommands:
+  extract   one-shot run (optionally filtered to a `--task`)
+  sweep     one-shot over every YAML in a directory
+  serve     long-lived in-process scheduler — replaces cron
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from briar.commands.base import Command
+from briar.errors import CliError
+from briar.formatting import render
+from briar.iac.runbook import (
+    RunbookScheduler,
+    extract_runbook,
+    load_runbook_file,
+)
+
+
+log = logging.getLogger(__name__)
+
+
+class CommandRunbook(Command):
+    name = "runbook"
+    help = "Run extractors and/or serve the in-process scheduler."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        sub = parser.add_subparsers(dest="op", required=True)
+
+        ex = sub.add_parser(
+            "extract",
+            help="walk a YAML's `extract:` or `schedules:` and write knowledge files",
+        )
+        ex.add_argument("file")
+        ex.add_argument(
+            "--task",
+            default="",
+            help="run only the schedule whose `task:` matches this name",
+        )
+
+        sw = sub.add_parser(
+            "sweep",
+            help="run extract for every *.yaml in a directory",
+        )
+        sw.add_argument("directory")
+
+        sv = sub.add_parser(
+            "serve",
+            help="long-running scheduler — registers every (company, task) " "and runs the schedule loop forever",
+        )
+        sv.add_argument("directory")
+        sv.add_argument(
+            "--tick",
+            type=float,
+            default=1.0,
+            help="seconds between schedule.run_pending() ticks (default: 1)",
+        )
+
+    def run(self, args: argparse.Namespace) -> int:
+        if args.op == "extract":
+            return self._extract(args)
+        if args.op == "sweep":
+            return self._sweep(args)
+        if args.op == "serve":
+            return self._serve(args)
+        raise CliError(f"unknown runbook op {args.op!r}")
+
+    def _extract(self, args: argparse.Namespace) -> int:
+        runbook = load_runbook_file(Path(args.file))
+        rows = extract_runbook(runbook, args.task)
+        items = [{"company": r.company, "task": r.task, "status": r.status, "output": r.output} for r in rows]
+        render(items, args.format, ["company", "task", "status", "output"])
+        return 0
+
+    def _sweep(self, args: argparse.Namespace) -> int:
+        root = Path(args.directory)
+        if not root.is_dir():
+            raise CliError(f"sweep: {root} is not a directory")
+        files = sorted(p for p in root.glob("*.yaml") if p.is_file())
+        if not files:
+            print(f"sweep: no *.yaml under {root}")
+            return 0
+        exit_code = 0
+        for path in files:
+            log.info("sweep: processing %s", path.name)
+            print(f"--- {path.name} ---")
+            try:
+                runbook = load_runbook_file(path)
+                rows = extract_runbook(runbook)
+                items = [{"company": r.company, "task": r.task, "status": r.status, "output": r.output} for r in rows]
+                render(items, args.format, ["company", "task", "status", "output"])
+            except Exception:  # noqa: BLE001
+                log.exception("sweep: %s failed", path.name)
+                exit_code = 1
+        return exit_code
+
+    def _serve(self, args: argparse.Namespace) -> int:
+        directory = Path(args.directory)
+        if not directory.is_dir():
+            raise CliError(f"serve: {directory} is not a directory")
+        scheduler = RunbookScheduler(directory)
+        for entry in scheduler.register_all():
+            log.info("registered company=%s task=%s every=%r", entry.company, entry.task, entry.every)
+        scheduler.run_forever(args.tick)
+        return 0

briar/commands/secrets.py

@@ -0,0 +1,165 @@
+"""`briar secrets` — credential management surface.
+
+Subcommands:
+  doctor   walk the configured runbooks + report which (company, extractor,
+           env var) tuples are set vs missing — without ever printing values.
+
+The doctor reads required env-var lists FROM THE PROVIDER CLASSES
+(``RepositoryProvider.required_env_vars`` / etc.) rather than from a
+hand-maintained ``(extractor × provider) → creds`` table. Adding a new
+extractor or provider needs no edit here — the provider declares its
+requirements and the doctor picks them up via
+``KnowledgeExtractor.provider_class_for(args)``."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import ClassVar, Dict
+
+from briar.commands.base import Command
+from briar.credentials import CredentialStoreRegistry, make_credential_store
+
+
+class CommandSecrets(Command):
+    name = "secrets"
+    help = "Inspect credential coverage (briar secrets doctor)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        sub = parser.add_subparsers(dest="secrets_action", required=True)
+
+        doctor = sub.add_parser("doctor", help="Audit (company, extractor) → env-var coverage")
+        doctor.add_argument(
+            "--examples",
+            type=Path,
+            default=Path("./examples"),
+            help="Runbook YAML directory (default: ./examples)",
+        )
+        doctor.add_argument(
+            "--store",
+            default="envfile",
+            choices=list(CredentialStoreRegistry.kinds()),
+            help="Credential store backend (default: envfile)",
+        )
+
+        from briar.credentials._bootstraps import CredentialBootstrapRegistry
+
+        bootstrap = sub.add_parser(
+            "bootstrap",
+            help="One-off invocation of a credential bootstrap (e.g. Infisical fetch). "
+            "Normally runs automatically at CLI startup; this subcommand is for testing.",
+        )
+        bootstrap.add_argument(
+            "--kind",
+            default="",
+            choices=list(CredentialBootstrapRegistry.kinds()),
+            help="Force one bootstrap backend. Default: auto-detect via is_available().",
+        )
+        bootstrap.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Run the remote fetch but DON'T write to os.environ. Prints the keys that "
+            "would be set, without revealing values.",
+        )
+
+    _ACTIONS: ClassVar[Dict[str, str]] = {
+        "doctor": "_doctor",
+        "bootstrap": "_bootstrap",
+    }
+
+    def run(self, args: argparse.Namespace) -> int:
+        handler_name = self._ACTIONS.get(args.secrets_action)
+        if handler_name is None:
+            known = ", ".join(sorted(self._ACTIONS.keys()))
+            print(f"unknown secrets action: {args.secrets_action} (known: {known})")
+            return 1
+        return getattr(self, handler_name)(args)
+
+    @staticmethod
+    def _bootstrap(args: argparse.Namespace) -> int:
+        from briar.credentials._bootstraps import auto_bootstrap, make_bootstrap
+
+        if args.kind:
+            bs = make_bootstrap(args.kind)
+            if not bs.is_available():
+                names = ", ".join(bs.required_env_vars())
+                print(f"bootstrap kind={bs.kind} not configured — required env: {names}")
+                return 1
+            result = bs.hydrate(dry_run=args.dry_run)
+        else:
+            result = auto_bootstrap(dry_run=args.dry_run)
+
+        if not result.ok:
+            print(f"bootstrap {result.backend} failed: {result.error}")
+            return 1
+        if result.backend == "(none)":
+            print("no credential-bootstrap backend configured (auto-detect found nothing)")
+            return 0
+        marker = "would write" if args.dry_run else "wrote"
+        print(f"bootstrap {result.backend}: {marker} {result.count} env vars (preserved {len(result.skipped)} already-set)")
+        if result.written:
+            print("  keys: " + ", ".join(sorted(result.written)))
+        return 0
+
+    def _doctor(self, args: argparse.Namespace) -> int:
+        from briar.extract import EXTRACTORS
+        from briar.iac.runbook import load_runbook_file
+        from briar.iac.runbook.executor import RunbookSchedules
+        from briar.messaging import WRITERS
+
+        store = make_credential_store(args.store)
+        examples_dir: Path = args.examples
+        if not examples_dir.exists():
+            print(f"no examples dir at {examples_dir}")
+            return 1
+
+        any_missing = False
+        for yaml_path in sorted(examples_dir.glob("*.yaml")):
+            try:
+                rb = load_runbook_file(yaml_path)
+            except Exception as exc:  # noqa: BLE001
+                print(f"  {yaml_path.name}: load failed — {exc}")
+                continue
+            for company_name, company in rb.companies.items():
+                print(f"\n=== {company_name} ({yaml_path.name}) ===")
+                for schedule in RunbookSchedules.for_company(company):
+                    for entry in schedule.extract:
+                        extractor = EXTRACTORS.get(entry.name)
+                        if extractor is None:
+                            print(f"  ?  {entry.name} — unknown extractor, skipping")
+                            continue
+                        # Synthesize the same Namespace the runbook
+                        # executor would build for this entry.
+                        ns = argparse.Namespace(company=company_name, **entry.args)
+                        provider_cls = extractor.provider_class_for(ns)
+                        if provider_cls is None:
+                            # Local-only / not provider-backed (no
+                            # credential dependency). Report as ok.
+                            print(f"  ok {entry.name} (no provider deps)")
+                            continue
+                        provider_kind = getattr(provider_cls, "kind", "?")
+                        required = provider_cls.required_env_vars(company=company_name)
+                        missing = [env_name for env_name in required if not store.read(env_name)]
+                        if missing:
+                            any_missing = True
+                            print(f"  X  {entry.name} (provider={provider_kind}) — MISSING: {', '.join(missing)}")
+                        else:
+                            print(f"  ok {entry.name} (provider={provider_kind})")
+
+                # Audit the `messages:` block too — each writer has its
+                # own required_env_vars classmethod, same shape as the
+                # provider audit above.
+                for handle, binding in (getattr(company, "messages", {}) or {}).items():
+                    kind = getattr(binding, "kind", "") or (binding.get("kind", "") if isinstance(binding, dict) else "")
+                    writer_cls = WRITERS.get(kind)
+                    if writer_cls is None:
+                        print(f"  ?  messages.{handle} (kind={kind}) — unknown writer, skipping")
+                        continue
+                    required = writer_cls.required_env_vars(company=company_name)
+                    missing = [env_name for env_name in required if not store.read(env_name)]
+                    if missing:
+                        any_missing = True
+                        print(f"  X  messages.{handle} (kind={kind}) — MISSING: {', '.join(missing)}")
+                    else:
+                        print(f"  ok messages.{handle} (kind={kind})")
+        return 1 if any_missing else 0

briar/commands/version.py

@@ -0,0 +1,17 @@
+"""`briar version` — local client version."""
+
+from __future__ import annotations
+
+import argparse
+
+from briar import __version__
+from briar.commands.base import Command
+
+
+class CommandVersion(Command):
+    name = "version"
+    help = "Print client version."
+
+    def run(self, args: argparse.Namespace) -> int:
+        print(f"briar-cli {__version__}")
+        return 0

briar/credentials/__init__.py

@@ -0,0 +1,48 @@
+"""Credential store registry. The `EnvFileStore` is the only fully
+working backend today; the rest are stubs that fail loudly so callers
+know to wire them up before depending on them."""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple, Type
+
+from briar._registry import build_registry
+from briar.credentials._store import CredentialStore
+from briar.credentials.aws_secrets import AwsSecretsManagerStore
+from briar.credentials.envfile import EnvFileStore
+from briar.credentials.infisical import InfisicalStore
+from briar.credentials.ssm import SsmParameterStore
+from briar.credentials.vault import VaultStore
+from briar.errors import CliError
+
+
+STORES: Dict[str, Type[CredentialStore]] = build_registry(
+    (EnvFileStore, AwsSecretsManagerStore, SsmParameterStore, VaultStore, InfisicalStore),
+    kind="credential store",
+    name_attr="kind",
+)
+
+
+class CredentialStoreRegistry:
+    @classmethod
+    def kinds(cls) -> Tuple[str, ...]:
+        return tuple(STORES.keys())
+
+    @classmethod
+    def make(cls, kind: str) -> CredentialStore:
+        store_cls = STORES.get(kind)
+        if store_cls is None:
+            known = ", ".join(sorted(STORES.keys()))
+            raise CliError(f"unknown credential store {kind!r}; known: {known}")
+        return store_cls()
+
+
+make_credential_store = CredentialStoreRegistry.make
+
+
+__all__ = [
+    "STORES",
+    "CredentialStore",
+    "CredentialStoreRegistry",
+    "make_credential_store",
+]

briar/credentials/_bootstrap.py

@@ -0,0 +1,93 @@
+"""`CredentialBootstrap` — bulk-write-at-startup credential hydration.
+
+Distinct from `CredentialStore` (read-on-demand at the call site).
+Where `CredentialStore.read(name)` is invoked by the doctor + by
+adapters that need one specific value, `CredentialBootstrap.hydrate()`
+runs ONCE at process startup, fetches every secret from a remote
+store, and writes them to `os.environ` so the rest of briar (the
+`CredEnv` enum, providers, writers, …) reads them through the
+standard env-var path.
+
+Two operating modes coexist:
+
+  /etc/briar/secrets.env        →  systemd EnvironmentFile=…  →  os.environ
+                                                                     ↑
+                                                       briar reads here
+
+  INFISICAL_CLIENT_ID + creds   →  InfisicalBootstrap.hydrate()  →  os.environ
+                                                                     ↑
+                                                       briar reads here
+
+The local file path is the simpler default. Bootstrap mode is for
+deployments where secrets live in a remote vault and the operator
+only wants to bake the machine-identity credentials onto the host —
+everything else is fetched at start.
+
+Strategy + Registry behind `_bootstraps/`; constructed by
+`make_bootstrap(kind)` or auto-selected by `auto_bootstrap()` (called
+from `briar.cli.main` before any command logic runs)."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import ClassVar, Dict, List
+
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class HydrateResult:
+    """Outcome of one bootstrap. `written` lists the env-var names
+    that were `os.environ.setdefault`-ed; `skipped` lists the names
+    that were already set in `os.environ` and therefore preserved
+    (caller intent wins over the remote vault)."""
+
+    backend: str
+    written: List[str] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return not self.error
+
+    @property
+    def count(self) -> int:
+        return len(self.written)
+
+
+class CredentialBootstrap(ABC):
+    """Strategy contract. Concrete adapters wrap one remote vault."""
+
+    kind: ClassVar[str] = ""
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True iff the bootstrap has the machine-identity credentials
+        it needs to authenticate against the remote vault. Without
+        this signal, `auto_bootstrap()` skips the backend (so a host
+        without Infisical creds is a no-op, not an error)."""
+
+    @abstractmethod
+    def hydrate(self, *, dry_run: bool = False) -> HydrateResult:
+        """Fetch every secret + write to `os.environ`. Uses
+        `setdefault` so an already-set env var (e.g. one populated by
+        systemd's EnvironmentFile=) takes precedence over the remote
+        value.
+
+        `dry_run=True` performs the remote fetch but does NOT write —
+        useful for `briar secrets bootstrap --dry-run` to see what
+        WOULD be set without leaking values into the process env.
+        Returns the same HydrateResult shape; `written` lists what
+        the non-dry-run would have written."""
+
+    @classmethod
+    def required_env_vars(cls) -> List[str]:
+        """The machine-identity env vars this bootstrap needs to
+        authenticate (NOT the secrets it fetches — those are
+        per-deployment). Used by `briar secrets doctor` to check
+        whether the bootstrap itself is configured."""
+        return []

briar/credentials/_bootstraps/__init__.py

@@ -0,0 +1,80 @@
+"""Credential-bootstrap registry — Strategy + Factory.
+
+Each bootstrap fetches every secret from a remote vault at process
+startup and writes them to `os.environ`. Distinct lifecycle from
+`CredentialStore` (which is on-demand reads); see `_bootstrap.py`
+for the contract.
+
+Adding a new vault (Doppler, 1Password CLI, AWS Parameter Store
+bulk-fetch, …) = one module here + one entry in the tuple. The
+``auto_bootstrap()`` helper picks the first available one — typical
+use is one bootstrap configured per host, not several."""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, Tuple, Type
+
+from briar._registry import build_registry
+from briar.credentials._bootstrap import CredentialBootstrap, HydrateResult
+from briar.credentials._bootstraps.infisical import InfisicalBootstrap
+from briar.errors import CliError
+
+
+log = logging.getLogger(__name__)
+
+
+BOOTSTRAPS: Dict[str, Type[CredentialBootstrap]] = build_registry(
+    (InfisicalBootstrap,),
+    kind="credential bootstrap",
+    name_attr="kind",
+)
+
+
+class CredentialBootstrapRegistry:
+    """Factory + introspection. Static."""
+
+    @classmethod
+    def kinds(cls) -> Tuple[str, ...]:
+        return tuple(BOOTSTRAPS.keys())
+
+    @classmethod
+    def make(cls, kind: str) -> CredentialBootstrap:
+        bs_cls = BOOTSTRAPS.get(kind)
+        if bs_cls is None:
+            known = ", ".join(sorted(BOOTSTRAPS.keys()))
+            raise CliError(f"unknown credential bootstrap {kind!r}; known: {known}")
+        return bs_cls()
+
+
+make_bootstrap = CredentialBootstrapRegistry.make
+
+
+def auto_bootstrap(*, dry_run: bool = False) -> HydrateResult:
+    """Iterate every registered bootstrap, run the first one whose
+    `is_available()` returns True. Called once from `briar.cli.main`
+    before any command logic runs.
+
+    Returns a `HydrateResult` even when no backend ran — callers
+    branch on `.ok` and `.count`. Logged at INFO level so a fresh
+    install with no bootstrap configured is self-explanatory in the
+    journalctl tail."""
+    for bs_cls in BOOTSTRAPS.values():
+        bs = bs_cls()
+        if not bs.is_available():
+            log.debug("credential-bootstrap: %s not configured — skip", bs.kind)
+            continue
+        log.info("credential-bootstrap: running %s%s", bs.kind, " (dry-run)" if dry_run else "")
+        return bs.hydrate(dry_run=dry_run)
+    log.debug("credential-bootstrap: no backend configured — using os.environ as-is")
+    return HydrateResult(backend="(none)")
+
+
+__all__ = [
+    "BOOTSTRAPS",
+    "CredentialBootstrap",
+    "CredentialBootstrapRegistry",
+    "HydrateResult",
+    "auto_bootstrap",
+    "make_bootstrap",
+]

briar/credentials/_bootstraps/infisical.py

@@ -0,0 +1,115 @@
+"""Infisical `CredentialBootstrap`.
+
+Lazy-imports `infisicalsdk` so it's an opt-in extra:
+``pip install briar-cli[infisical]``.
+
+Auth: universal-auth machine identity. Three env vars
+(`INFISICAL_CLIENT_ID`, `INFISICAL_CLIENT_SECRET`, `INFISICAL_PROJECT_ID`)
+plus optional `INFISICAL_ENV` (defaults to ``prod``) and
+`INFISICAL_HOST` (defaults to ``https://app.infisical.com``).
+
+`hydrate()` calls `client.secrets.list_secrets()` for the configured
+project + environment, then `os.environ.setdefault(k, v)` for each
+secret. Already-set env vars (e.g. populated by systemd before briar
+starts) take precedence — matches the operator-intent-wins
+semantics in the design doc."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Any, List, Optional
+
+from briar.credentials._bootstrap import CredentialBootstrap, HydrateResult
+
+
+log = logging.getLogger(__name__)
+
+
+def _import_infisical_sdk() -> Optional[Any]:
+    try:
+        return importlib.import_module("infisical_sdk")
+    except ImportError:
+        return None
+
+
+class InfisicalBootstrap(CredentialBootstrap):
+    kind = "infisical"
+    DEFAULT_HOST = "https://app.infisical.com"
+    DEFAULT_ENV = "prod"
+
+    REQUIRED_VARS: tuple = (
+        "INFISICAL_CLIENT_ID",
+        "INFISICAL_CLIENT_SECRET",
+        "INFISICAL_PROJECT_ID",
+    )
+
+    def __init__(self) -> None:
+        self._client_id = os.environ.get("INFISICAL_CLIENT_ID", "")
+        self._client_secret = os.environ.get("INFISICAL_CLIENT_SECRET", "")
+        self._project_id = os.environ.get("INFISICAL_PROJECT_ID", "")
+        self._env = os.environ.get("INFISICAL_ENV", self.DEFAULT_ENV)
+        self._host = os.environ.get("INFISICAL_HOST", self.DEFAULT_HOST)
+        self._client = None
+
+    def is_available(self) -> bool:
+        return all((self._client_id, self._client_secret, self._project_id))
+
+    def hydrate(self, *, dry_run: bool = False) -> HydrateResult:
+        if not self.is_available():
+            return HydrateResult(backend=self.kind, error="missing INFISICAL_{CLIENT_ID,CLIENT_SECRET,PROJECT_ID}")
+        try:
+            secrets = self._fetch_secrets()
+        except Exception as exc:  # noqa: BLE001 — surface as result, don't crash startup
+            log.exception("infisical fetch failed")
+            return HydrateResult(backend=self.kind, error=f"fetch failed: {exc}")
+
+        written: List[str] = []
+        skipped: List[str] = []
+        for key, value in secrets:
+            if not key:
+                continue
+            if key in os.environ:
+                skipped.append(key)
+                continue
+            if not dry_run:
+                # setdefault — but we already checked `key not in os.environ`
+                # above so this is effectively just `os.environ[key] = value`.
+                # Kept as setdefault for the race-safe semantics under
+                # concurrent imports.
+                os.environ.setdefault(key, value)
+            written.append(key)
+
+        log.info(
+            "infisical-bootstrap: backend=%s wrote=%d preserved=%d host=%s env=%s%s",
+            self.kind,
+            len(written),
+            len(skipped),
+            self._host,
+            self._env,
+            " (DRY RUN — nothing written)" if dry_run else "",
+        )
+        return HydrateResult(backend=self.kind, written=written, skipped=skipped)
+
+    def _fetch_secrets(self) -> List[tuple]:
+        sdk = _import_infisical_sdk()
+        if sdk is None:
+            raise RuntimeError("infisical_sdk not installed — run `pip install briar-cli[infisical]`")
+        if self._client is None:
+            self._client = sdk.InfisicalSDKClient(host=self._host)
+            self._client.auth.universal_auth.login(
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+            )
+        result = self._client.secrets.list_secrets(
+            project_id=self._project_id,
+            environment_slug=self._env,
+            secret_path="/",
+        )
+        # Tolerate both attribute and dict shapes since SDK versions vary.
+        return [(getattr(s, "secretKey", None) or s.get("secretKey", ""), getattr(s, "secretValue", None) or s.get("secretValue", "")) for s in (result.secrets or [])]
+
+    @classmethod
+    def required_env_vars(cls) -> List[str]:
+        return list(cls.REQUIRED_VARS)