kitden 0.1.1__py3-none-any.whl

kitden/__init__.py

@@ -0,0 +1,3 @@
+"""See and safely change what AI coding clients load on this computer."""
+
+__version__ = "0.1.1"

kitden/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m kitden`, used to start the page in the background."""
+
+import sys
+
+from kitden.cli import main
+
+sys.exit(main())

kitden/changes/actions.py

@@ -0,0 +1,91 @@
+"""Turn a requested action into steps for the change engine (write-matrix.md)."""
+
+import re
+from pathlib import Path
+
+from kitden.clients.base import PLUGIN_DISABLE, PLUGIN_ENABLE, REMOVE_DIRECT, ClientAdapter
+from kitden.model import Gateway, Item, Step
+
+GATEWAY_CONNECT = "gateway.connect"
+SETUP_SERVER_UPDATE = "setup_server.update"
+ENTRY_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}")
+
+
+def connect_steps(
+    adapters: dict[str, ClientAdapter], clients: list[str], gateway: Gateway, name: str
+) -> list[Step]:
+    """One gateway entry per chosen client, in the user scope (FR-024, FR-033)."""
+    if not ENTRY_NAME.fullmatch(name):
+        raise ValueError("The entry name may use letters, digits, '-' and '_' only")
+    if not clients:
+        raise ValueError("Choose at least one client")
+    steps = []
+    for client in dict.fromkeys(clients):
+        adapter = adapters.get(client)
+        if adapter is None:
+            raise ValueError(f"{client} cannot be connected to a gateway")
+        steps.append(adapter.gateway_step(gateway, name))
+    return steps
+
+
+def remove_steps(adapters: dict[str, ClientAdapter], item: Item) -> list[Step]:
+    """Remove one direct MCP entry (FR-026)."""
+    adapter = adapters.get(item.client)
+    if adapter is None or REMOVE_DIRECT not in item.actions:
+        raise ValueError(f"{item.name} cannot be removed here")
+    return [adapter.remove_step(item)]
+
+
+def plugin_steps(adapters: dict[str, ClientAdapter], item: Item, enable: bool) -> list[Step]:
+    """Turn one plugin on or off (FR-027). Cursor and account plugins have no control."""
+    action = PLUGIN_ENABLE if enable else PLUGIN_DISABLE
+    adapter = adapters.get(item.client)
+    if adapter is None or action not in item.actions:
+        raise ValueError(f"{item.name} cannot be turned {'on' if enable else 'off'} here")
+    return [adapter.plugin_step(item, enable)]
+
+
+def setup_server_steps(
+    adapters: dict[str, ClientAdapter], clients: list[str], command: str
+) -> list[Step]:
+    """Add the read-only setup server to the chosen clients (FR-032).
+
+    GUI clients may not see the shell PATH, so the entry uses an absolute path (research R9).
+    """
+    if not Path(command).is_absolute():
+        raise ValueError("The setup server needs the absolute path of the kitden command")
+    if not clients:
+        raise ValueError("Choose at least one client")
+    steps = []
+    for client in dict.fromkeys(clients):
+        adapter = adapters.get(client)
+        if adapter is None:
+            raise ValueError(f"The setup server cannot be added to {client}")
+        steps.append(adapter.setup_server_step(command, ["mcp"]))
+    return steps
+
+
+def update_steps(
+    adapters: dict[str, ClientAdapter],
+    items: list[Item],
+    added_clients: set[str],
+    command: str | None,
+) -> list[Step]:
+    """Replace old `agentsetup` entries with `kitden` (feature 002, FR-006).
+
+    Per client: remove the old entry, then add `kitden` unless that client already has it. Both
+    steps edit one settings file; the engine applies them in order.
+    """
+    if not items:
+        raise ValueError("Choose an old Kitden entry.")
+    steps = []
+    for item in items:
+        adapter = adapters.get(item.client)
+        if adapter is None:
+            raise ValueError("Choose an old Kitden entry.")
+        steps.append(adapter.remove_step(item))
+        if item.client not in added_clients:
+            if command is None or not Path(command).is_absolute():
+                raise ValueError("The setup server needs the absolute path of the kitden command")
+            steps.append(adapter.setup_server_step(command, ["mcp"]))
+    return steps

kitden/changes/atomic.py

@@ -0,0 +1,60 @@
+"""Write a file so that readers see either the old bytes or the new bytes, never a mix.
+
+Research R7: resolve symlinks, refuse hard links, temp file in the same folder, keep the mode,
+full fsync on macOS, then rename over the target.
+"""
+
+import contextlib
+import fcntl
+import os
+import secrets
+import stat
+from pathlib import Path
+
+NEW_FILE_MODE = 0o600
+
+
+class RefusedWriteError(Exception):
+    """The file must not be written this way."""
+
+
+def _full_fsync(fd: int) -> None:
+    # On macOS plain fsync does not flush the drive cache; F_FULLFSYNC does.
+    try:
+        fcntl.fcntl(fd, fcntl.F_FULLFSYNC)
+    except (AttributeError, OSError):
+        os.fsync(fd)
+
+
+def write_atomic(path: Path | str, data: bytes) -> Path:
+    """Replace the file at `path` (or the file it links to) with `data`. Returns the real path."""
+    target = Path(os.path.realpath(path))
+    try:
+        info = target.stat()
+    except FileNotFoundError:
+        mode = NEW_FILE_MODE
+    else:
+        if info.st_nlink > 1:
+            raise RefusedWriteError(f"{target} has a hard link; renaming would break it")
+        mode = stat.S_IMODE(info.st_mode)
+
+    temp = target.with_name(f".{target.name}.{secrets.token_hex(4)}.tmp")
+    fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fchmod(handle.fileno(), mode)
+            _full_fsync(handle.fileno())
+        os.replace(temp, target)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            temp.unlink()
+        raise
+
+    folder = os.open(target.parent, os.O_RDONLY)
+    try:
+        os.fsync(folder)
+    finally:
+        os.close(folder)
+    return target

kitden/changes/backup.py

@@ -0,0 +1,113 @@
+"""Backups and the change log (research R7, FR-017, FR-022).
+
+Folders are 0700 and files 0600. A backup holds the original bytes, which may contain secrets;
+the manifest and the log never do. A backup is removed only when it is older than 30 days and not
+one of the newest 100 changes.
+"""
+
+import hashlib
+import json
+import os
+import shutil
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from kitden.redact import redact, redact_text
+
+KEEP_DAYS = 30
+KEEP_COUNT = 100
+
+
+def _private_folder(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+    path.chmod(0o700)
+
+
+def _write_private(path: Path, data: bytes, append: bool = False) -> None:
+    flags = os.O_WRONLY | os.O_CREAT | (os.O_APPEND if append else os.O_TRUNC)
+    fd = os.open(path, flags, 0o600)
+    try:
+        os.fchmod(fd, 0o600)
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def _hide_text(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, dict):
+        return {k: _hide_text(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_hide_text(v) for v in value]
+    return value
+
+
+class ChangeStore:
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self.folder = self.root / "changes"
+        self.log_path = self.root / "changes.log"
+
+    def _change_folder(self, change_id: str) -> Path:
+        for path in (self.root, self.folder, self.folder / change_id):
+            _private_folder(path)
+        return self.folder / change_id
+
+    def backup(self, change_id: str, files: dict[str, bytes | None]) -> dict[str, Path | None]:
+        """Save the original bytes of each file (None = the file did not exist)."""
+        folder = self._change_folder(change_id)
+        saved: dict[str, Path | None] = {}
+        manifest = []
+        for index, (path, data) in enumerate(files.items()):
+            entry: dict[str, Any] = {"path": path, "existed": data is not None}
+            saved[path] = None
+            if data is not None:
+                copy = folder / f"{index}-{Path(path).name}"
+                _write_private(copy, data)
+                saved[path] = copy
+                entry["sha256"] = hashlib.sha256(data).hexdigest()
+            manifest.append(entry)
+        record = {"change": change_id, "files": manifest}
+        _write_private(folder / "manifest.json", json.dumps(record, indent=2).encode())
+        return saved
+
+    def save(self, change_id: str, record: dict) -> None:
+        """Keep what undo needs. Lives next to the backup and is just as private."""
+        folder = self._change_folder(change_id)
+        _write_private(folder / "change.json", json.dumps(record, indent=2).encode())
+
+    def load(self) -> list[dict]:
+        records = []
+        for path in sorted(self.folder.glob("*/change.json")) if self.folder.is_dir() else []:
+            try:
+                records.append(json.loads(path.read_text()))
+            except (OSError, ValueError):
+                continue
+        return records
+
+    def log(self, entry: dict) -> None:
+        _private_folder(self.root)
+        line = json.dumps(_hide_text(redact(entry)[0]), ensure_ascii=False)
+        _write_private(self.log_path, (line + "\n").encode(), append=True)
+
+    def entries(self) -> list[dict]:
+        """Change log entries, newest first."""
+        if not self.log_path.is_file():
+            return []
+        lines = self.log_path.read_text().splitlines()
+        return [json.loads(line) for line in reversed(lines) if line.strip()]
+
+    def prune(self, now: datetime | None = None) -> None:
+        if not self.folder.is_dir():
+            return
+        cutoff = (now or datetime.now(UTC)) - timedelta(days=KEEP_DAYS)
+        folders = sorted(p for p in self.folder.iterdir() if p.is_dir())
+        for folder in folders[:-KEEP_COUNT]:
+            try:
+                made = datetime.strptime(folder.name[:16], "%Y%m%dT%H%M%SZ").replace(tzinfo=UTC)
+            except ValueError:
+                continue
+            if made < cutoff:
+                shutil.rmtree(folder)

kitden/changes/client_cli.py

@@ -0,0 +1,55 @@
+"""Run a client's own command (FR-021), for example `claude mcp add-json`. Output is redacted."""
+
+import os
+import shutil
+import subprocess  # noqa: S404 - runs fixed client commands without a shell
+from dataclasses import dataclass
+from pathlib import Path
+
+from kitden.redact import redact_text
+
+TIMEOUT_SECONDS = 60.0
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    returncode: int
+    output: str
+
+
+def find_command(name: str, home: Path) -> str | None:
+    """The client binary on PATH, or in the places its installer uses."""
+    found = shutil.which(name)
+    if found:
+        return found
+    for candidate in (home / ".local/bin" / name, home / ".claude/local" / name):
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+class CommandRunner:
+    """Runs commands with HOME set to the home folder the page shows."""
+
+    def __init__(self, home: Path, timeout: float = TIMEOUT_SECONDS) -> None:
+        self.home = Path(home)
+        self.timeout = timeout
+
+    def __call__(self, command: list[str], cwd: str | None) -> CommandResult:
+        binary = find_command(command[0], self.home)
+        if binary is None:
+            return CommandResult(127, f"{command[0]} was not found")
+        env = {**os.environ, "HOME": str(self.home)}
+        try:
+            done = subprocess.run(  # noqa: S603 - fixed client command, no shell
+                [binary, *command[1:]],
+                cwd=cwd,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as error:
+            return CommandResult(1, redact_text(str(error)))
+        return CommandResult(done.returncode, redact_text((done.stdout + done.stderr).strip()))