keld 0.1.0__tar.gz

keld-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/

keld-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: keld
+Version: 0.1.0
+Summary: Keld CLI — set up local telemetry for AI coding tools
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# keld
+
+The Keld CLI configures your local AI coding tools (Claude Code, Codex, Gemini
+CLI) to send telemetry to Keld Atlas.
+
+## Install
+
+Recommended (isolated, works on every platform):
+
+```bash
+pipx install keld
+```
+
+If you don't have pipx yet: `python -m pip install --user pipx && python -m pipx ensurepath`.
+
+Alternatives: `uvx keld` / `uv tool install keld` (if you use uv), or
+`pip install keld` **inside a virtual environment** (a bare `pip install` into
+system Python fails with `externally-managed-environment` on modern distros).
+
+## Usage
+
+```bash
+keld login             # authenticate (also happens automatically on first `signal setup`)
+
+keld signal setup      # detect tools, show changes, configure telemetry + install hook
+keld signal status     # see what's configured
+keld signal doctor     # diagnose problems
+keld signal uninstall  # cleanly remove everything Keld added
+```
+
+Auth commands (`login`, `logout`, `whoami`) are top-level and shared across
+Keld product groups. Telemetry onboarding lives under the `keld signal` group.
+
+`keld signal setup` flags: `--tool claude_code,codex` (target specific tools),
+`--dry-run` (show changes only), `--yes` (skip confirmation),
+`--no-login` (fail instead of opening a browser, for CI).
+
+`setup` is interactive. By default it prints a concise summary of the changes to
+each config file; pass `--diff` to see the full unified diff. If a tool's config
+already has settings Keld can't safely merge (e.g. Codex with its own `[otel]`
+section), setup explains the conflict and lets you **[s]kip** that tool,
+**[r]eplace** just the conflicting section with Keld's (the rest of your config
+is preserved, and the diff is always shown for a replace), or **[a]bort**. Every
+file Keld modifies is first copied to `~/.keld/backups/<tool>/`. Use `--dry-run`
+to preview without writing and `--yes` to skip prompts (conflicts are
+auto-skipped in that mode).
+
+### Local development
+
+To point the CLI at a Keld server running locally, pass `--api-url` to `keld
+login` (or `keld signal setup`):
+
+```bash
+keld login --api-url http://localhost:8000   # auth against the local server
+keld signal setup                            # remembered — uses the same server
+```
+
+The chosen URL is stored with your credentials, so subsequent commands target it
+automatically. `--api-url` overrides the `KELD_API_URL` environment variable,
+which does the same thing if you prefer setting it in your shell.
+
+## Authentication
+
+`keld` signs you in with a **browser-based device authorization** flow — you
+approve the CLI from a normal signed-in Keld session, so your password is never
+typed into (or seen by) the terminal.
+
+```mermaid
+sequenceDiagram
+    actor You
+    participant CLI as keld CLI
+    participant Browser
+    participant Keld
+
+    You->>CLI: keld login (or any `keld signal` command)
+    CLI->>Keld: start device authorization
+    Keld-->>CLI: verification URL + short code
+    CLI->>Browser: open the verification URL
+    You->>Browser: sign in to Keld and confirm the code
+    Browser->>Keld: approve (from your authenticated session)
+    loop until you approve (or the request expires)
+        CLI->>Keld: check whether it's approved yet
+        Keld-->>CLI: not yet… then: an access token
+    end
+    CLI->>CLI: save the token locally (your user only)
+    Note over CLI,Keld: keld signal setup then uses that token to fetch your<br/>telemetry config and set up your local tools
+```
+
+Key points:
+
+- **Lazy by default** — you don't have to run `keld login` first. Any command
+  that needs auth (e.g. `keld signal setup`) starts this flow automatically; on a
+  CI box use `--no-login` to fail cleanly instead of opening a browser.
+- **You approve, in the browser** — the short code shown in your terminal is only
+  meaningful to confirm inside an authenticated Keld session, and the approval is
+  attributed to the signed-in person. The request stops working shortly after it
+  is issued if left unapproved.
+- **The token stays on your machine** — it's written under `~/.keld` with
+  user-only file permissions (override the location with `KELD_HOME`). `keld
+  whoami` shows who you're signed in as; `keld logout` removes it. Tokens are
+  revocable from Keld, so a lost laptop can be cut off without rotating anything
+  else.
+
+## Environment
+
+- `KELD_HOME` — where credentials, the hook, and the manifest live (default `~/.keld`).
+- `KELD_API_URL` — Atlas base URL (default `https://atlas.keld.co`).

keld-0.1.0/README.md

@@ -0,0 +1,107 @@
+# keld
+
+The Keld CLI configures your local AI coding tools (Claude Code, Codex, Gemini
+CLI) to send telemetry to Keld Atlas.
+
+## Install
+
+Recommended (isolated, works on every platform):
+
+```bash
+pipx install keld
+```
+
+If you don't have pipx yet: `python -m pip install --user pipx && python -m pipx ensurepath`.
+
+Alternatives: `uvx keld` / `uv tool install keld` (if you use uv), or
+`pip install keld` **inside a virtual environment** (a bare `pip install` into
+system Python fails with `externally-managed-environment` on modern distros).
+
+## Usage
+
+```bash
+keld login             # authenticate (also happens automatically on first `signal setup`)
+
+keld signal setup      # detect tools, show changes, configure telemetry + install hook
+keld signal status     # see what's configured
+keld signal doctor     # diagnose problems
+keld signal uninstall  # cleanly remove everything Keld added
+```
+
+Auth commands (`login`, `logout`, `whoami`) are top-level and shared across
+Keld product groups. Telemetry onboarding lives under the `keld signal` group.
+
+`keld signal setup` flags: `--tool claude_code,codex` (target specific tools),
+`--dry-run` (show changes only), `--yes` (skip confirmation),
+`--no-login` (fail instead of opening a browser, for CI).
+
+`setup` is interactive. By default it prints a concise summary of the changes to
+each config file; pass `--diff` to see the full unified diff. If a tool's config
+already has settings Keld can't safely merge (e.g. Codex with its own `[otel]`
+section), setup explains the conflict and lets you **[s]kip** that tool,
+**[r]eplace** just the conflicting section with Keld's (the rest of your config
+is preserved, and the diff is always shown for a replace), or **[a]bort**. Every
+file Keld modifies is first copied to `~/.keld/backups/<tool>/`. Use `--dry-run`
+to preview without writing and `--yes` to skip prompts (conflicts are
+auto-skipped in that mode).
+
+### Local development
+
+To point the CLI at a Keld server running locally, pass `--api-url` to `keld
+login` (or `keld signal setup`):
+
+```bash
+keld login --api-url http://localhost:8000   # auth against the local server
+keld signal setup                            # remembered — uses the same server
+```
+
+The chosen URL is stored with your credentials, so subsequent commands target it
+automatically. `--api-url` overrides the `KELD_API_URL` environment variable,
+which does the same thing if you prefer setting it in your shell.
+
+## Authentication
+
+`keld` signs you in with a **browser-based device authorization** flow — you
+approve the CLI from a normal signed-in Keld session, so your password is never
+typed into (or seen by) the terminal.
+
+```mermaid
+sequenceDiagram
+    actor You
+    participant CLI as keld CLI
+    participant Browser
+    participant Keld
+
+    You->>CLI: keld login (or any `keld signal` command)
+    CLI->>Keld: start device authorization
+    Keld-->>CLI: verification URL + short code
+    CLI->>Browser: open the verification URL
+    You->>Browser: sign in to Keld and confirm the code
+    Browser->>Keld: approve (from your authenticated session)
+    loop until you approve (or the request expires)
+        CLI->>Keld: check whether it's approved yet
+        Keld-->>CLI: not yet… then: an access token
+    end
+    CLI->>CLI: save the token locally (your user only)
+    Note over CLI,Keld: keld signal setup then uses that token to fetch your<br/>telemetry config and set up your local tools
+```
+
+Key points:
+
+- **Lazy by default** — you don't have to run `keld login` first. Any command
+  that needs auth (e.g. `keld signal setup`) starts this flow automatically; on a
+  CI box use `--no-login` to fail cleanly instead of opening a browser.
+- **You approve, in the browser** — the short code shown in your terminal is only
+  meaningful to confirm inside an authenticated Keld session, and the approval is
+  attributed to the signed-in person. The request stops working shortly after it
+  is issued if left unapproved.
+- **The token stays on your machine** — it's written under `~/.keld` with
+  user-only file permissions (override the location with `KELD_HOME`). `keld
+  whoami` shows who you're signed in as; `keld logout` removes it. Tokens are
+  revocable from Keld, so a lost laptop can be cut off without rotating anything
+  else.
+
+## Environment
+
+- `KELD_HOME` — where credentials, the hook, and the manifest live (default `~/.keld`).
+- `KELD_API_URL` — Atlas base URL (default `https://atlas.keld.co`).

keld-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "keld"
+version = "0.1.0"
+description = "Keld CLI — set up local telemetry for AI coding tools"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["typer>=0.12", "httpx>=0.27", "rich>=13"]
+
+[project.scripts]
+keld = "keld.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/keld"]
+
+# Keep the sdist to shippable source only — exclude internal dev artifacts
+# (.superpowers/, docs/ plans, tests) that would otherwise be published.
+[tool.hatch.build.targets.sdist]
+include = ["src/keld", "README.md", "pyproject.toml"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

keld-0.1.0/src/keld/__init__.py

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

keld-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)