keld 0.1.0__py3-none-any.whl

keld/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

keld/api/client.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from ..errors import KeldError
+
+
+@dataclass
+class DeviceStart:
+    device_code: str
+    user_code: str
+    verification_url: str
+    interval: int
+    expires_in: int
+
+
+@dataclass
+class Onboarding:
+    endpoint: str
+    ingest_token: str
+    actor: str
+
+
+class AtlasClient:
+    def __init__(self, base_url: str, token: str | None = None, transport=None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._transport = transport
+        self._http = httpx.Client(base_url=self.base_url, timeout=30.0, transport=transport)
+
+    def _post(self, path: str, **kwargs) -> httpx.Response:
+        try:
+            return self._http.post(path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise KeldError(f"network error contacting Atlas: {exc}") from exc
+
+    def _check(self, resp: httpx.Response) -> None:
+        if resp.status_code >= 400:
+            raise KeldError(f"Atlas returned {resp.status_code}: {resp.text[:200]}")
+
+    def device_start(self) -> DeviceStart:
+        resp = self._post("/v1/cli/device/start")
+        self._check(resp)
+        return DeviceStart(**resp.json())
+
+    def device_poll(self, device_code: str) -> dict | None:
+        resp = self._post("/v1/cli/device/poll", json={"device_code": device_code})
+        if resp.status_code == 202:
+            return None
+        self._check(resp)
+        return resp.json()
+
+    def onboarding(self) -> Onboarding:
+        if not self.token:
+            raise KeldError("onboarding requires authentication")
+        try:
+            resp = self._http.get("/v1/cli/onboarding",
+                                  headers={"Authorization": f"Bearer {self.token}"})
+        except httpx.HTTPError as exc:
+            raise KeldError(f"network error contacting Atlas: {exc}") from exc
+        self._check(resp)
+        return Onboarding(**resp.json())
+
+    def fetch_hook(self, endpoint: str, ingest_token: str) -> bytes:
+        url = f"{endpoint.rstrip('/')}/v1/tool-context/hook.py"
+        try:
+            with httpx.Client(timeout=30.0, transport=self._transport) as client:
+                resp = client.get(url, params={"token": ingest_token})
+        except httpx.HTTPError as exc:
+            raise KeldError(f"network error downloading hook: {exc}") from exc
+        self._check(resp)
+        return resp.content

keld/auth/device_flow.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import time
+import webbrowser
+
+from ..api.client import AtlasClient
+from ..console import console
+from ..errors import KeldError
+from ..paths import api_base
+from .store import AuthData, load_auth, save_auth
+
+
+def login(client: AtlasClient, *, open_browser: bool = True,
+          sleep=time.sleep, opener=webbrowser.open) -> AuthData:
+    ds = client.device_start()
+    console.print(
+        f"To authorize this device, open:\n  [bold]{ds.verification_url}[/]\n"
+        f"The code [bold]{ds.user_code}[/] is already filled in — "
+        f"confirm it matches, then approve."
+    )
+    if open_browser:
+        console.print("(Opening your browser…)")
+        opener(ds.verification_url)
+
+    waited = 0
+    while waited <= ds.expires_in:
+        result = client.device_poll(ds.device_code)
+        if result is not None:
+            auth = AuthData(access_token=result["access_token"],
+                            principal=result["principal"], org=result["org"],
+                            api_url=client.base_url)
+            save_auth(auth)
+            console.print(f"Logged in as [bold]{auth.principal}[/] (org: {auth.org})")
+            return auth
+        sleep(ds.interval)
+        waited += max(ds.interval, 1)
+    raise KeldError("login timed out; please run `keld login` again")
+
+
+def require_auth(*, no_login: bool, open_browser: bool = True) -> AuthData:
+    existing = load_auth()
+    if existing is not None:
+        return existing
+    if no_login:
+        raise KeldError("not logged in (run `keld login`; --no-login was set)")
+    return login(AtlasClient(api_base()), open_browser=open_browser)

keld/auth/store.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+
+from ..paths import auth_path, keld_home
+
+
+@dataclass
+class AuthData:
+    access_token: str
+    principal: str
+    org: str
+    api_url: str
+
+
+def save_auth(auth: AuthData) -> None:
+    keld_home().mkdir(parents=True, exist_ok=True)
+    path = auth_path()
+    path.write_text(json.dumps(asdict(auth), indent=2) + "\n")
+    os.chmod(path, 0o600)
+
+
+def load_auth() -> AuthData | None:
+    path = auth_path()
+    if not path.exists():
+        return None
+    return AuthData(**json.loads(path.read_text()))
+
+
+def clear_auth() -> bool:
+    path = auth_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False

keld/cli.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import typer
+
+from .commands import login as login_cmd
+from .commands import setup as setup_cmd
+from .commands import status as status_cmd
+from .commands import uninstall as uninstall_cmd
+from .console import console_err
+from .errors import KeldError
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Keld CLI")
+
+# Top-level auth commands — shared across all product groups.
+app.command()(login_cmd.login)
+app.command()(login_cmd.logout)
+app.command()(login_cmd.whoami)
+
+# `keld signal <cmd>` — Keld Signal telemetry onboarding for local tools.
+signal_app = typer.Typer(
+    no_args_is_help=True,
+    help="Set up Keld Signal telemetry for your local AI coding tools.",
+)
+signal_app.command()(setup_cmd.setup)
+signal_app.command()(status_cmd.status)
+signal_app.command("doctor")(status_cmd.doctor)
+signal_app.command()(uninstall_cmd.uninstall)
+app.add_typer(signal_app, name="signal")
+
+
+def main() -> None:
+    try:
+        app()
+    except KeldError as exc:
+        console_err.print(f"[bold red]Error:[/] {exc}")
+        raise SystemExit(1)

keld/commands/login.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import typer
+
+from ..auth.device_flow import require_auth
+from ..auth.store import clear_auth, load_auth
+from ..config.manifest import Manifest
+from ..console import console, fail
+from ..paths import set_api_base_override
+
+
+def login(
+    no_login: bool = typer.Option(False, "--no-login",
+                                  help="Fail instead of opening a browser."),
+    api_url: str = typer.Option(None, "--api-url", metavar="URL",
+                                help="Target a different Keld API base URL "
+                                     "(e.g. http://localhost:8000) for local dev."),
+) -> None:
+    """Authenticate to Keld."""
+    if api_url:
+        set_api_base_override(api_url)
+    auth = require_auth(no_login=no_login)
+    console.print(f"Logged in as [bold]{auth.principal}[/] (org: {auth.org})")
+
+
+def logout() -> None:
+    """Remove stored credentials."""
+    if clear_auth():
+        console.print("Logged out.")
+    else:
+        console.print("Not logged in.")
+
+
+def whoami() -> None:
+    """Show the logged-in principal."""
+    auth = load_auth()
+    if auth is None:
+        fail("not logged in (run `keld login`)")
+    endpoint = Manifest.load().endpoint
+    suffix = f" · endpoint {endpoint}" if endpoint else ""
+    console.print(f"[bold]{auth.principal}[/] · org {auth.org} · {auth.api_url}{suffix}")

keld/commands/setup.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import typer
+
+from .. import diffview
+from ..api.client import AtlasClient, Onboarding
+from ..auth.device_flow import require_auth
+from ..config.manifest import Manifest, ToolManifest
+from ..config.writer import backup_config, write_atomic
+from ..console import console
+from ..errors import KeldError
+from ..hook import install_hook
+from ..paths import api_base_override, set_api_base_override
+from ..tools.base import Plan, SetupParams
+from ..tools.registry import select_adapters
+
+
+def _default_resolve_conflict(adapter, plan) -> str:
+    """Prompt for a conflicted tool. Returns "skip", "replace", or "abort"."""
+    choice = typer.prompt(
+        f"{adapter.display_name}: [s]kip this tool, [r]eplace the conflicting "
+        f"section, or [a]bort everything?",
+        default="s",
+    ).strip().lower()[:1]
+    return {"s": "skip", "r": "replace", "a": "abort"}.get(choice, "skip")
+
+
+def _run_setup(adapters, params: SetupParams, client: AtlasClient, ob: Onboarding,
+               *, dry_run: bool, yes: bool, show_diff: bool = False,
+               confirm=typer.confirm, resolve_conflict=None) -> Manifest:
+    if resolve_conflict is None:
+        resolve_conflict = _default_resolve_conflict
+
+    approved = []  # list[tuple[adapter, Plan]]
+    for adapter in adapters:
+        path = adapter.config_path()
+        before = path.read_text() if path.exists() else None
+        console.rule(f"[bold]{adapter.display_name}[/] · {path}")
+        try:
+            plan = adapter.apply(before, params)
+        except KeldError as exc:
+            plan = Plan(name=adapter.name, config_path=path, after_text=before or "",
+                        managed={}, summary=[], changed=False, conflict=str(exc))
+
+        if plan.conflict:
+            console.print(f"  [yellow]conflict:[/] {plan.conflict}")
+            if dry_run:
+                console.print("  [dim](dry-run: would be skipped)[/]")
+                continue
+            if yes:
+                console.print("  [yellow]skipped[/] (--yes)")
+                continue
+            choice = resolve_conflict(adapter, plan)
+            if choice == "abort":
+                console.print("Aborted.")
+                raise typer.Exit(code=1)
+            if choice == "replace":
+                plan = adapter.apply(before, params, replace=True)
+                if plan.conflict:
+                    console.print(f"  [yellow]can't replace:[/] {plan.conflict}")
+                    console.print("  [yellow]skipped[/]")
+                    continue
+                diffview.render(before, plan.after_text, plan.config_path)  # replace: always
+                for line in plan.summary:
+                    console.print(f"  [dim]{line}[/]")
+                approved.append((adapter, plan))
+                continue
+            console.print("  [yellow]skipped[/]")
+            continue
+
+        if not plan.changed:
+            console.print("  already configured — no changes")
+            continue
+
+        if show_diff:
+            diffview.render(before, plan.after_text, plan.config_path)
+        for line in plan.summary:
+            console.print(f"  [dim]{line}[/]")
+        approved.append((adapter, plan))
+
+    console.print("\n[bold]Hook[/] · keld-context.py → ~/.keld")
+
+    if dry_run:
+        console.print("\n[dim]--dry-run: no changes written.[/]")
+        return Manifest.load()
+    if not approved:
+        console.print("\nNothing to apply.")
+        return Manifest.load()
+    if not yes and not confirm(f"Apply {len(approved)} change(s)?"):
+        console.print("Aborted.")
+        return Manifest.load()
+
+    manifest = Manifest(endpoint=ob.endpoint, actor=ob.actor)
+    manifest.hook = install_hook(client, ob)
+    for adapter, plan in approved:
+        backup = backup_config(plan.config_path, adapter.name)
+        if backup:
+            console.print(f"  [dim]backed up {plan.config_path} → {backup}[/]")
+        write_atomic(plan.config_path, plan.after_text, backup=False)
+        manifest.tools[adapter.name] = ToolManifest(
+            name=adapter.name, config_path=str(plan.config_path),
+            managed=plan.managed, backup_path=str(backup) if backup else None)
+        console.print(f"  [green]✓[/] {adapter.display_name}")
+
+    manifest.save()
+    console.print("\nSetup complete. Restart any running sessions to pick up the new config.")
+    return manifest
+
+
+def setup(
+    tool: str = typer.Option("", "--tool", help="Comma-separated tools to target."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show changes without writing."),
+    diff: bool = typer.Option(False, "--diff", help="Show full unified diffs (default: summary only)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+    no_login: bool = typer.Option(False, "--no-login", help="Fail instead of opening a browser."),
+    api_url: str = typer.Option(None, "--api-url", metavar="URL",
+                                help="Target a different Keld API base URL "
+                                     "(e.g. http://localhost:8000) for local dev."),
+) -> None:
+    """Configure detected tools for Keld telemetry."""
+    if api_url:
+        set_api_base_override(api_url)
+    auth = require_auth(no_login=no_login)
+    client = AtlasClient(api_base_override() or auth.api_url, token=auth.access_token)
+    ob = client.onboarding()
+    names = [t.strip() for t in tool.split(",") if t.strip()] or None
+    adapters = select_adapters(names)
+    if not adapters:
+        console.print("No supported tools detected. Use --tool to target one explicitly.")
+        raise typer.Exit(code=0)
+    params = SetupParams(endpoint=ob.endpoint, ingest_token=ob.ingest_token, actor=ob.actor)
+    _run_setup(adapters, params, client, ob, dry_run=dry_run, yes=yes, show_diff=diff)

keld/commands/status.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ..auth.store import load_auth
+from ..config.manifest import Manifest
+from ..console import console
+from ..tools.base import ToolStatus
+from ..tools.registry import ALL_ADAPTERS
+
+
+def _read(path: Path) -> str | None:
+    return path.read_text() if path.exists() else None
+
+
+def _collect_status(manifest: Manifest) -> list[tuple[str, ToolStatus]]:
+    rows = []
+    for adapter in ALL_ADAPTERS:
+        tm = manifest.tools.get(adapter.name)
+        managed = tm.managed if tm else None
+        st = adapter.status(_read(adapter.config_path()), managed)
+        rows.append((adapter.display_name, st))
+    return rows
+
+
+def status() -> None:
+    """Show local Keld configuration state."""
+    auth = load_auth()
+    if auth is None:
+        console.print("[yellow]Not logged in[/] (run `keld login`)")
+    else:
+        console.print(f"Logged in: [bold]{auth.principal}[/] · org {auth.org} · {auth.api_url}")
+
+    manifest = Manifest.load()
+    for display_name, st in _collect_status(manifest):
+        state = "[green]configured[/]" if st.configured else (
+            "not configured" if st.installed else "[dim]not installed[/]")
+        console.print(f"  {display_name:14} {state}")
+    if manifest.hook:
+        console.print(f"  hook            v{manifest.hook.version}")
+
+
+def doctor() -> None:
+    """Diagnose Keld configuration problems."""
+    problems: list[str] = []
+    manifest = Manifest.load()
+
+    for name, tm in manifest.tools.items():
+        adapter = next((a for a in ALL_ADAPTERS if a.name == name), None)
+        if adapter is None:
+            continue
+        st = adapter.status(_read(Path(tm.config_path)), tm.managed)
+        if not st.configured:
+            problems.append(f"{adapter.display_name}: manifest records setup but config is not "
+                            f"configured (drift). Re-run `keld setup`.")
+
+    if manifest.hook and not Path(manifest.hook.path).exists():
+        problems.append("hook script is missing. Re-run `keld setup`.")
+
+    if problems:
+        for p in problems:
+            console.print(f"  [red]✗[/] {p}")
+        raise typer.Exit(code=1)
+    console.print("[green]No problems found.[/]")

keld/commands/uninstall.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ..config.manifest import Manifest
+from ..config.writer import delete_if_empty, write_atomic
+from ..console import console
+from ..paths import hook_path
+from ..tools.registry import get_adapter
+
+
+def _run_uninstall(manifest: Manifest, names: list[str] | None,
+                   *, yes: bool, confirm=typer.confirm) -> None:
+    targets = [n for n in manifest.tools if (names is None or n in names)]
+    if not targets:
+        console.print("Nothing to uninstall.")
+        return
+    if not yes and not confirm(f"Remove Keld config from {', '.join(targets)}?"):
+        console.print("Aborted.")
+        return
+
+    for name in targets:
+        tm = manifest.tools[name]
+        adapter = get_adapter(name)
+        path = Path(tm.config_path)
+        current = path.read_text() if path.exists() else None
+        plan = adapter.remove(current, tm.managed)
+        if tm.managed.get("created") and delete_if_empty(path, plan.after_text):
+            pass
+        else:
+            write_atomic(path, plan.after_text, backup=False)
+        bak = path.with_name(path.name + ".keld.bak")
+        if bak.exists():
+            bak.unlink()
+        del manifest.tools[name]
+        console.print(f"  [green]✓[/] {adapter.display_name}")
+
+    if not manifest.tools:
+        if hook_path().exists():
+            hook_path().unlink()
+        if manifest.hook:
+            manifest.hook = None
+        manifest.endpoint = None
+        manifest.actor = None
+    manifest.save()
+    console.print("Done.")
+
+
+def uninstall(
+    tool: str = typer.Option("", "--tool", help="Comma-separated tools to target."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Remove Keld telemetry config and hook."""
+    names = [t.strip() for t in tool.split(",") if t.strip()] or None
+    _run_uninstall(Manifest.load(), names, yes=yes)

keld/config/manifest.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from ..paths import keld_home, manifest_path
+
+
+@dataclass
+class HookRecord:
+    path: str
+    version: str
+    sha256: str
+
+
+@dataclass
+class ToolManifest:
+    name: str
+    config_path: str
+    managed: dict = field(default_factory=dict)
+    backup_path: str | None = None
+
+
+@dataclass
+class Manifest:
+    endpoint: str | None = None
+    actor: str | None = None
+    tools: dict[str, ToolManifest] = field(default_factory=dict)
+    hook: HookRecord | None = None
+
+    @classmethod
+    def load(cls) -> "Manifest":
+        path = manifest_path()
+        if not path.exists():
+            return cls()
+        return cls.from_dict(json.loads(path.read_text()))
+
+    def save(self) -> None:
+        keld_home().mkdir(parents=True, exist_ok=True)
+        manifest_path().write_text(json.dumps(self.to_dict(), indent=2) + "\n")
+
+    def to_dict(self) -> dict:
+        return {
+            "endpoint": self.endpoint,
+            "actor": self.actor,
+            "tools": {k: vars(v) for k, v in self.tools.items()},
+            "hook": vars(self.hook) if self.hook else None,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Manifest":
+        tools = {k: ToolManifest(**v) for k, v in (d.get("tools") or {}).items()}
+        hook = HookRecord(**d["hook"]) if d.get("hook") else None
+        return cls(endpoint=d.get("endpoint"), actor=d.get("actor"), tools=tools, hook=hook)

keld/config/merge.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+import tomllib
+
+from ..errors import KeldError
+
+
+def load_json(text: str | None) -> dict:
+    if not text or not text.strip():
+        return {}
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise KeldError(f"existing config is not valid JSON: {exc}") from exc
+
+
+def dump_json(obj: dict) -> str:
+    return json.dumps(obj, indent=2) + "\n"
+
+
+def merge_env(obj: dict, env: dict[str, str]) -> list[str]:
+    section = obj.setdefault("env", {})
+    section.update(env)
+    return list(env.keys())
+
+
+def remove_section_keys(obj: dict, section: str, keys: list[str]) -> None:
+    sec = obj.get(section)
+    if not isinstance(sec, dict):
+        return
+    for key in keys:
+        sec.pop(key, None)
+    if not sec:
+        obj.pop(section, None)
+
+
+def add_claude_hook(obj: dict, event: str, matcher: str | None, command: str) -> None:
+    entry: dict = {"hooks": [{"type": "command", "command": command}]}
+    if matcher is not None:
+        entry = {"matcher": matcher, **entry}
+    arr = obj.setdefault("hooks", {}).setdefault(event, [])
+    if entry not in arr:
+        arr.append(entry)
+
+
+def has_hook_with_command(obj: dict, substr: str) -> bool:
+    hooks = obj.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+    return substr in json.dumps(hooks)
+
+
+def remove_hooks_by_command(obj: dict, substr: str) -> None:
+    hooks = obj.get("hooks")
+    if not isinstance(hooks, dict):
+        return
+    for event in list(hooks):
+        arr = hooks[event]
+        arr[:] = [e for e in arr if substr not in json.dumps(e)]
+        if not arr:
+            del hooks[event]
+    if not hooks:
+        obj.pop("hooks", None)
+
+
+KELD_TOML_START = "# >>> keld (managed by keld CLI — do not edit between markers)"
+KELD_TOML_END = "# <<< keld"
+
+
+def has_keld_block(text: str | None) -> bool:
+    return bool(text) and KELD_TOML_START in text
+
+
+def strip_keld_block(text: str | None) -> str:
+    if not text or KELD_TOML_START not in text:
+        return text or ""
+    lines = text.splitlines()
+    out: list[str] = []
+    inside = False
+    for line in lines:
+        if line.strip() == KELD_TOML_START:
+            inside = True
+            continue
+        if inside and line.strip() == KELD_TOML_END:
+            inside = False
+            continue
+        if not inside:
+            out.append(line)
+    result = "\n".join(out).rstrip("\n")
+    return result + "\n" if result else ""
+
+
+def upsert_keld_block(text: str | None, body: str) -> str:
+    base = strip_keld_block(text)
+    body = body if body.endswith("\n") else body + "\n"
+    block = f"{KELD_TOML_START}\n{body}{KELD_TOML_END}\n"
+    if not base.strip():
+        return block
+    return base + "\n" + block
+
+
+def validate_toml(text: str) -> None:
+    try:
+        tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise KeldError(f"resulting TOML is invalid: {exc}") from exc
+
+
+def strip_toml_table(text: str, table: str) -> str:
+    """Remove a top-level [table] (and its [table.sub] subtables) from raw TOML
+    text, preserving all other content. No-op if the table is absent.
+
+    Walks lines tracking the current top-level table (first dotted segment of
+    the most recent [header]/[[header]]); drops lines while it equals `table`.
+    """
+    out: list[str] = []
+    dropping = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if stripped.startswith("["):
+            header = stripped.strip("[]").strip()
+            top = header.split(".", 1)[0].strip().strip('"').strip("'")
+            dropping = top == table
+        if not dropping:
+            out.append(line)
+    return "".join(out)