caland 0.5.0__py3-none-any.whl

caland/__main__.py

@@ -0,0 +1,4 @@
+from .app import main
+
+if __name__ == "__main__":
+    main()

caland/app.py

@@ -0,0 +1,183 @@
+"""Caland — a terminal Databricks secret manager.
+
+The App is the composition root: it builds the infrastructure adapters, wires
+them into the `OnboardingService`, installs the theme, and hands off to
+`MainScreen`. Domain logic lives in `caland.domain`, use-cases in
+`caland.application`, adapters in `caland.infrastructure`; UI in
+`caland.interface`.
+"""
+
+from __future__ import annotations
+
+from textual.app import App
+
+from .application import OnboardingService, WorkspaceService
+from .domain import Settings, SettingsStore
+from .infrastructure import (
+    DatabricksBundleStore,
+    DatabricksCfgProfileStore,
+    DatabricksConnector,
+    JsonSettingsStore,
+)
+from .interface.screens.main import MainScreen
+from .interface.theme import CALAND_THEMES
+
+
+class EphemeralSettingsStore:
+    """Fallback `SettingsStore`: keeps preferences for this process only.
+
+    The default for programmatic use (tests, embedding) so constructing the app
+    never touches the user's real config; `main()` passes the JSON store.
+    """
+
+    def __init__(self) -> None:
+        self._settings = Settings()
+
+    def load(self) -> Settings:
+        return self._settings
+
+    def save(self, settings: Settings) -> None:
+        self._settings = settings
+
+
+class CalandApp(App[None]):
+    CSS_PATH = "styles.tcss"
+    TITLE = "Caland"
+    # `q` quits from the browse/login screens only (they bind it themselves) —
+    # an app-level binding would bubble up from dialogs and quit mid-confirm.
+
+    def __init__(
+        self,
+        onboarding: OnboardingService | None = None,
+        session: WorkspaceService | None = None,
+        read_only: bool = False,
+        settings_store: SettingsStore | None = None,
+        profile: str | None = None,
+    ) -> None:
+        super().__init__()
+        self._onboarding = onboarding
+        self._initial_session = session
+        self.read_only = read_only
+        self._settings_store = settings_store or EphemeralSettingsStore()
+        self.settings = self._settings_store.load()
+        self._profile = profile  # workspace to auto-connect to (--profile)
+
+    def get_theme_variable_defaults(self) -> dict[str, str]:
+        # The stylesheet is parsed under Textual's default theme before ours is
+        # applied, so the per-section accents must resolve there too. Each
+        # Caland theme overrides these with its own values.
+        return {
+            **super().get_theme_variable_defaults(),
+            "scopes-color": "#8b7cff",
+            "secrets-color": "#4ec9e0",
+            "detail-color": "#e0b24a",
+            "value-color": "#5fd39a",
+        }
+
+    def save_settings(self) -> None:
+        self._settings_store.save(self.settings)
+
+    def _remember_theme(self, theme: str) -> None:
+        self.settings.theme = theme
+        self.save_settings()
+
+    def on_mount(self) -> None:
+        for theme in CALAND_THEMES:
+            self.register_theme(theme)
+        # apply the persisted theme (fall back if it no longer exists), then
+        # remember every change the user makes via the palette
+        wanted = self.settings.theme
+        self.theme = wanted if wanted in self.available_themes else "caland"
+        self.watch(self, "theme", self._remember_theme, init=False)
+        onboarding = self._onboarding or OnboardingService(
+            DatabricksConnector(),
+            DatabricksCfgProfileStore(),
+            DatabricksBundleStore(),
+        )
+        self.push_screen(
+            MainScreen(
+                onboarding,
+                self._initial_session,
+                read_only=self.read_only,
+                settings=self.settings,
+                save_settings=self.save_settings,
+                auto_connect=self._profile,
+            )
+        )
+
+
+_USAGE = """\
+caland — a keyboard-driven terminal UI for managing Databricks secrets.
+
+usage: caland [WORKSPACE] [--profile NAME] [--read-only] [--version] [--help]
+       caland --page [WORKSPACE] [--no-open]
+
+  WORKSPACE / --profile NAME
+                connect straight to a discovered workspace (a
+                ~/.databrickscfg profile or bundle target) and skip
+                the picker
+  --read-only   browse, reveal, and copy — but disable every mutation
+                (safe for poking around production)
+  --page        a preview: caland as a page in your browser, served from
+                this machine only. It browses, shows and copies; it does
+                not change anything yet
+  --no-open     with --page: print the link instead of opening a browser
+
+Run with no arguments to launch the TUI. Inside: ? for help, ctrl+p for the
+command palette, q to quit.
+"""
+
+
+def main() -> None:
+    import sys
+
+    args = sys.argv[1:]
+    if {"-V", "--version"} & set(args):
+        from importlib.metadata import version
+
+        print(f"caland {version('caland')}")
+        return
+    if {"-h", "--help"} & set(args):
+        print(_USAGE, end="")
+        return
+    profile: str | None = None
+    if "--profile" in args:
+        i = args.index("--profile")
+        if i + 1 >= len(args):
+            print("error: --profile needs a workspace name", file=sys.stderr)
+            raise SystemExit(2)
+        profile = args[i + 1]
+    else:  # a bare positional is the workspace name
+        positional = [a for a in args if not a.startswith("-")]
+        if positional:
+            profile = positional[0]
+    if "--page" in args:
+        raise SystemExit(_page(profile, args))
+    CalandApp(
+        read_only="--read-only" in args,
+        settings_store=JsonSettingsStore(),
+        profile=profile,
+    ).run()
+
+
+def _page(profile: str | None, args: list[str]) -> int:
+    """`caland --page`: the same workspace, as a page in the browser."""
+    from importlib.metadata import version
+
+    from .interface import web
+
+    onboarding = OnboardingService(
+        DatabricksConnector(), DatabricksCfgProfileStore(), DatabricksBundleStore()
+    )
+    return web.run(
+        onboarding,
+        profile,
+        read_only="--read-only" in args,
+        settings=JsonSettingsStore().load(),
+        version=version("caland"),
+        open_browser="--no-open" not in args,
+    )
+
+
+if __name__ == "__main__":
+    main()

caland/application/__init__.py

@@ -0,0 +1,22 @@
+"""Application layer — use-cases that orchestrate the domain.
+
+Depends only on `domain`; never on infrastructure or the UI. The read model
+(`WorkspaceCache`) is pure in-memory app state, so it lives here too.
+"""
+
+from .dotenv import format_dotenv, parse_dotenv
+from .loading import Loader, Progress
+from .onboarding import Connection, OnboardingService
+from .read_model import WorkspaceCache
+from .workspace import WorkspaceService
+
+__all__ = [
+    "Connection",
+    "Loader",
+    "OnboardingService",
+    "Progress",
+    "WorkspaceCache",
+    "WorkspaceService",
+    "format_dotenv",
+    "parse_dotenv",
+]

caland/application/dotenv.py

@@ -0,0 +1,52 @@
+"""Parse and format .env content for bulk secret import/export.
+
+Pure text transforms — no I/O. Values with newlines or other awkward characters
+are written JSON-quoted and read back the same way, so multiline secrets
+(PEM keys etc.) round-trip.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# values that can be written bare, without quoting
+_BARE = re.compile(r"^[A-Za-z0-9_@%+=:,./-]*$")
+
+
+def parse_dotenv(text: str) -> dict[str, str]:
+    """KEY=VALUE lines. Blank lines and #-comments are ignored, an `export `
+    prefix is dropped, and single/double/JSON-style quotes are stripped."""
+    entries: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key.startswith("export "):
+            key = key.removeprefix("export ").strip()
+        value = value.strip()
+        if value[:1] == '"' and value[-1:] == '"' and len(value) >= 2:
+            try:
+                value = json.loads(value)  # unescape \n etc.
+            except ValueError:
+                value = value[1:-1]
+        elif value[:1] == "'" and value[-1:] == "'" and len(value) >= 2:
+            value = value[1:-1]
+        if key:
+            entries[key] = value
+    return entries
+
+
+def format_dotenv(pairs: list[tuple[str, str]], *, redact: bool = False) -> str:
+    """Render pairs as .env lines; `redact` writes keys only (a template)."""
+    lines = []
+    for key, value in pairs:
+        if redact:
+            lines.append(f"{key}=")
+        elif _BARE.match(value):
+            lines.append(f"{key}={value}")
+        else:
+            lines.append(f"{key}={json.dumps(value)}")
+    return "\n".join(lines) + "\n"

caland/application/loading.py

@@ -0,0 +1,138 @@
+"""Loader — connect to a workspace and warm it, in the background.
+
+The use-case behind "the page is there before the workspace is": something that
+shows a workspace starts a `Loader`, draws at once, and asks `progress()` how far
+it is. Scopes are warmed eight at a time — enough that hundreds are ready in
+seconds, few enough not to hammer the API.
+
+It does no I/O of its own: `connect` hands it a `WorkspaceService`, and every
+call goes through that.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, replace
+
+from ..domain import AuthError, StoreError
+from .workspace import WorkspaceService
+
+#: How many scopes are asked for at the same time.
+WORKERS = 8
+
+CONNECTING = "connecting"
+LOADING = "loading"
+READY = "ready"
+FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class Progress:
+    """How far a `Loader` is. `version` goes up with every change, so that who
+    asks can tell whether there is anything new."""
+
+    phase: str = CONNECTING
+    done: int = 0
+    total: int = 0
+    error: str = ""
+    version: int = 0
+
+
+class Loader:
+    def __init__(
+        self, connect: Callable[[], WorkspaceService], workers: int = WORKERS
+    ) -> None:
+        self._connect = connect
+        self._workers = workers
+        self._lock = threading.Lock()
+        self._progress = Progress()
+        self._service: WorkspaceService | None = None
+        # one run at a time: a refresh asked for during a load waits its turn
+        self._turn = threading.Lock()
+
+    @property
+    def service(self) -> WorkspaceService | None:
+        """The workspace, once connected."""
+        return self._service
+
+    def progress(self) -> Progress:
+        with self._lock:
+            return self._progress
+
+    # -- starting work --------------------------------------------------
+    def start(self) -> threading.Thread:
+        """Connect, sign in and warm every scope. Returns at once."""
+        return self._run(self._load)
+
+    def refresh(self, scope: str | None = None) -> threading.Thread | None:
+        """Read one scope again, or with no name the whole workspace. Returns at
+        once; nothing happens when there is no workspace to read."""
+        if self._service is None:
+            return None
+        if scope is None:
+            return self._run(self._warm)
+        return self._run(lambda: self._warm_one(scope))
+
+    def _run(self, work: Callable[[], None]) -> threading.Thread:
+        def in_turn() -> None:
+            with self._turn:
+                work()
+
+        thread = threading.Thread(target=in_turn, name="caland-loader", daemon=True)
+        thread.start()
+        return thread
+
+    # -- the work -------------------------------------------------------
+    def _set(self, **changes: object) -> None:
+        with self._lock:
+            now = self._progress
+            self._progress = replace(now, **changes, version=now.version + 1)
+
+    def _one_more(self) -> None:
+        with self._lock:
+            now = self._progress
+            self._progress = replace(now, done=now.done + 1, version=now.version + 1)
+
+    def _load(self) -> None:
+        self._set(phase=CONNECTING, done=0, total=0, error="")
+        try:
+            service = self._connect()
+            identity = service.authenticate()
+        except (AuthError, StoreError) as exc:
+            self._set(phase=FAILED, error=str(exc))
+            return
+        if not identity.authenticated:
+            self._set(phase=FAILED, error=identity.error or "Access denied.")
+            return
+        self._service = service
+        self._warm()
+
+    def _warm(self) -> None:
+        service = self._service
+        if service is None:
+            return
+        self._set(phase=LOADING, done=0, total=0, error="")
+        try:
+            scopes = service.load_scopes()
+        except StoreError as exc:
+            self._set(phase=FAILED, error=str(exc))
+            return
+        self._set(total=len(scopes))
+
+        def warm(name: str) -> None:
+            service.warm_scope(name)  # never raises: a scope it can't read is empty
+            self._one_more()
+
+        # each scope is written under its own key, so the writes don't race
+        with ThreadPoolExecutor(max_workers=self._workers) as pool:
+            list(pool.map(warm, [scope.name for scope in scopes]))
+        self._set(phase=READY)
+
+    def _warm_one(self, scope: str) -> None:
+        service = self._service
+        if service is None or service.scope(scope) is None:
+            return
+        service.refresh_scope(scope)
+        self._set()  # nothing but the version: there is something new to read

caland/application/onboarding.py

@@ -0,0 +1,106 @@
+"""OnboardingService — connection/login use-cases.
+
+Depends only on domain ports (`WorkspaceConnector`, `ProfileStore`, `BundleStore`);
+the composition root injects concrete infrastructure adapters. Produces
+ready-to-use `WorkspaceService` instances so the UI never touches the store or
+the SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..domain import (
+    SOURCE_PROFILE,
+    AuthError,
+    BundleStore,
+    ProfileStore,
+    Workspace,
+    WorkspaceConnector,
+)
+from .workspace import WorkspaceService
+
+
+@dataclass
+class Connection:
+    """A live workspace session plus the host needed to persist it as a profile."""
+
+    service: WorkspaceService
+    host: str = ""
+
+
+def _on_offer(workspaces: list[Workspace]) -> str:
+    names = ", ".join(workspace.name for workspace in workspaces)
+    return f"There is: {names}." if names else "There is none to choose from."
+
+
+class OnboardingService:
+    def __init__(
+        self,
+        connector: WorkspaceConnector,
+        profiles: ProfileStore,
+        bundle: BundleStore | None = None,
+    ) -> None:
+        self._connector = connector
+        self._profiles = profiles
+        self._bundle = bundle
+
+    # -- discovery ------------------------------------------------------
+    def available_workspaces(self) -> list[Workspace]:
+        """Every workspace we can offer, each tagged with where it came from: the
+        bundle target (default) first, then the ~/.databrickscfg profiles."""
+        workspaces: list[Workspace] = []
+        seen: set[str] = set()
+        bundle = self._bundle.discover() if self._bundle else None
+        if bundle:
+            workspaces.append(bundle)
+            seen.add(bundle.host_label)
+        for ws in self._profiles.discover():
+            if ws.host_label and ws.host_label in seen:
+                continue  # already offered by the bundle
+            seen.add(ws.host_label)
+            workspaces.append(ws)
+        return workspaces
+
+    def choose(self, name: str | None = None) -> Workspace:
+        """The workspace that was asked for by name — or, with no name, the one
+        there is no doubt about: the bundle's default, or the only one there is.
+
+        Raises `AuthError` saying what there is to choose from otherwise.
+        """
+        workspaces = self.available_workspaces()
+        if name:
+            for workspace in workspaces:
+                if workspace.name == name:
+                    return workspace
+            raise AuthError(f"No workspace “{name}” found. {_on_offer(workspaces)}")
+        default = next((w for w in workspaces if w.default), None)
+        if default:
+            return default
+        if len(workspaces) == 1:
+            return workspaces[0]
+        if not workspaces:
+            raise AuthError(
+                "No workspace found: there is no databricks.yml here and no profile "
+                "in ~/.databrickscfg."
+            )
+        raise AuthError(f"Which workspace? {_on_offer(workspaces)}")
+
+    def save_profile(self, name: str, host: str) -> None:
+        self._profiles.save(name, host)
+
+    # -- connection use-cases -------------------------------------------
+    def connect(self, workspace: Workspace) -> Connection:
+        """Connect to a chosen workspace. A saved profile uses its stored auth; a
+        bundle target or manual URL signs in through the browser (OAuth)."""
+        if workspace.source == SOURCE_PROFILE and workspace.profile:
+            return self.connect_profile(workspace.profile)
+        return self.connect_url(workspace.host)
+
+    def connect_profile(self, profile: str) -> Connection:
+        c = self._connector.connect_profile(profile)
+        return Connection(WorkspaceService(c.store, c.label))
+
+    def connect_url(self, host: str) -> Connection:
+        c = self._connector.connect_url(host)
+        return Connection(WorkspaceService(c.store, c.label), host=c.host)

caland/application/read_model.py

@@ -0,0 +1,76 @@
+"""WorkspaceCache — the in-memory read model the UI renders from.
+
+A projection that the application service warms up front (US-14) and keeps in
+sync on writes. Pure data + bookkeeping; it holds no business rules (those live
+in the domain) and does no I/O.
+
+Strategy (US-14/16):
+  * On connect the service warms scopes -> secret metadata -> ACLs in the
+    background.
+  * Secret *values* are NOT bulk-loaded; they are fetched lazily on reveal and
+    cached thereafter, so sensitive material isn't pulled into memory needlessly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..domain import Acl, Identity, Scope, Secret
+
+
+@dataclass
+class WorkspaceCache:
+    label: str
+    identity: Identity = field(default_factory=Identity)
+
+    scopes: list[Scope] = field(default_factory=list)
+    secrets: dict[str, list[Secret]] = field(default_factory=dict)
+    acls: dict[str, list[Acl]] = field(default_factory=dict)
+    values: dict[tuple[str, str], str] = field(default_factory=dict)
+    # scopes whose secrets we could list ⇒ the user holds at least READ on them
+    readable: set[str] = field(default_factory=set)
+
+    scopes_loaded: bool = False
+    warm_error: str = ""
+
+    # -- lookups ------------------------------------------------------------
+    def secrets_for(self, scope: str) -> list[Secret]:
+        return self.secrets.get(scope, [])
+
+    def acls_for(self, scope: str) -> list[Acl]:
+        return self.acls.get(scope, [])
+
+    def cached_value(self, scope: str, key: str) -> str | None:
+        return self.values.get((scope, key))
+
+    def set_value(self, scope: str, key: str, value: str) -> None:
+        self.values[(scope, key)] = value
+
+    # -- mutation keeping the read model + UI consistent --------------------
+    def upsert_secret(self, secret: Secret) -> None:
+        rows = self.secrets.setdefault(secret.scope, [])
+        for i, existing in enumerate(rows):
+            if existing.key == secret.key:
+                rows[i] = secret
+                break
+        else:
+            rows.append(secret)
+        rows.sort(key=lambda s: s.key.lower())
+
+    def remove_secret(self, scope: str, key: str) -> None:
+        self.secrets[scope] = [s for s in self.secrets.get(scope, []) if s.key != key]
+        self.values.pop((scope, key), None)
+
+    def add_scope(self, scope: Scope) -> None:
+        if not any(s.name == scope.name for s in self.scopes):
+            self.scopes.append(scope)
+            self.scopes.sort(key=lambda s: s.name.lower())
+        self.secrets.setdefault(scope.name, [])
+        self.acls.setdefault(scope.name, [])
+
+    def remove_scope(self, name: str) -> None:
+        self.scopes = [s for s in self.scopes if s.name != name]
+        self.secrets.pop(name, None)
+        self.acls.pop(name, None)
+        self.readable.discard(name)
+        self.values = {k: v for k, v in self.values.items() if k[0] != name}