cinna-cli 0.1.0__py3-none-any.whl

cinna/__init__.py

@@ -0,0 +1,3 @@
+"""cinna-cli — Local development CLI for Cinna Core agents."""
+
+__version__ = "0.1.0"

cinna/auth.py

@@ -0,0 +1,42 @@
+"""CLI token management — storage, header injection, validation."""
+
+import json
+import base64
+import time
+
+from cinna.config import CinnaConfig
+
+
+def get_auth_headers(config: CinnaConfig) -> dict[str, str]:
+    """Return Authorization header dict for API calls."""
+    return {"Authorization": f"Bearer {config.cli_token}"}
+
+
+def validate_token_locally(token: str) -> dict:
+    """Decode JWT without verification to check expiry.
+
+    Returns payload dict. Used for local "is this token probably expired?"
+    check before making API calls. The real validation happens server-side.
+
+    NOTE: This is NOT security validation — the backend validates the token.
+    This is a UX convenience to show a clear message instead of a 401.
+    """
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return {}
+        # Add padding
+        payload_b64 = parts[1] + "=" * (4 - len(parts[1]) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+        return payload
+    except Exception:
+        return {}
+
+
+def is_token_expired(token: str) -> bool:
+    """Check if the JWT token is probably expired (local check only)."""
+    payload = validate_token_locally(token)
+    exp = payload.get("exp")
+    if exp is None:
+        return False
+    return time.time() > exp

cinna/bootstrap.py

@@ -0,0 +1,278 @@
+"""Setup flow: exchange token, install Mutagen, clone workspace, start sync."""
+
+import logging
+import os
+import platform
+import re
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+import click
+import httpx
+
+from cinna.config import (
+    CinnaConfig,
+    KnowledgeSource,
+    find_workspace_root,
+    load_config,
+    save_config,
+    upsert_agent_registry,
+    workspace_dir,
+)
+from cinna.client import PlatformClient
+from cinna.sync import extract_workspace_tarball, ensure_workspace_dirs
+from cinna.mutagen_runtime import ensure_mutagen_ready
+from cinna import sync_session
+from cinna.context import (
+    generate_context_files,
+    generate_mcp_json,
+    generate_opencode_json,
+    generate_gitignore,
+)
+from cinna import console
+
+logger = logging.getLogger("cinna.bootstrap")
+
+
+def parse_setup_input(
+    raw_input: str, fallback_platform_url: str | None = None
+) -> tuple[str, str]:
+    """Parse setup input into (platform_url, token).
+
+    Accepts any of:
+      - Full curl command: 'curl -sL http://host:8000/cli-setup/TOKEN | python3 -'
+      - URL:               'http://host:8000/cli-setup/TOKEN'
+      - Raw token:         'TOKEN' (falls back to ``fallback_platform_url`` or
+                            the ``CINNA_PLATFORM_URL`` env var — in that order)
+
+    Returns (platform_url, token).
+    """
+    text = raw_input.strip().strip("'\"")
+
+    url_match = re.search(r"(https?://[^\s]+/cli-setup/[^\s|\"']+)", text)
+    if url_match:
+        url = url_match.group(1)
+        parsed = urlparse(url)
+        path_parts = parsed.path.rstrip("/").split("/cli-setup/")
+        if len(path_parts) == 2 and path_parts[1]:
+            token = path_parts[1]
+            prefix = path_parts[0]
+            platform_url = f"{parsed.scheme}://{parsed.netloc}{prefix}"
+            return platform_url, token
+
+    if text.startswith("http://") or text.startswith("https://") or "curl" in text:
+        raise click.ClickException(
+            "Could not parse setup URL from input. Expected a URL containing /cli-setup/TOKEN."
+        )
+
+    platform_url = fallback_platform_url or os.environ.get("CINNA_PLATFORM_URL", "")
+    if not platform_url:
+        raise click.ClickException(
+            "Cannot determine platform URL from the provided token.\n"
+            "Either paste the full curl command / URL from the platform UI,\n"
+            "or set the CINNA_PLATFORM_URL environment variable."
+        )
+    return platform_url, text
+
+
+def normalize_agent_dir_name(name: str) -> str:
+    """Normalize agent name to a lowercase, dash-separated directory name."""
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return slug or "agent"
+
+
+def _exchange_setup_token(
+    platform_url: str, token: str, machine_name: str
+) -> dict:
+    """POST /cli-setup/{token} and return the decoded payload.
+
+    Wraps the HTTP call in a uniform ClickException on failure so both
+    `setup` and `set-token` report errors the same way.
+    """
+    setup_url = f"{platform_url.rstrip('/')}/cli-setup/{token}"
+    machine_info = f"{platform.system()}/{platform.machine()}"
+    logger.info("Exchanging setup token at %s", setup_url)
+
+    response = httpx.post(
+        setup_url,
+        json={"machine_name": machine_name, "machine_info": machine_info},
+        timeout=30.0,
+    )
+    logger.debug("Setup response: %s %s", response.status_code, response.text[:500])
+    if response.status_code != 200:
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+        raise click.ClickException(f"Setup failed: {detail}")
+    return response.json()
+
+
+def run_set_token(setup_input: str, machine_name: str) -> None:
+    """Replace the CLI token on an existing workspace without rebuilding.
+
+    Called by `cinna set-token <token_or_url>`. Accepts the same input forms
+    as `cinna setup`. Verifies the exchanged token belongs to the agent this
+    workspace is already bound to before writing it.
+    """
+    root = find_workspace_root()
+    config = load_config(root)
+
+    # ``config.platform_url`` is stored as the bare host (PlatformClient adds
+    # ``/api/...`` itself). The cli-setup endpoint lives under ``/api``, so
+    # append it here before handing to parse_setup_input as a fallback.
+    stored_base = config.platform_url.rstrip("/")
+    fallback = stored_base if stored_base.endswith("/api") else f"{stored_base}/api"
+    platform_url, token = parse_setup_input(
+        setup_input, fallback_platform_url=fallback
+    )
+    payload = _exchange_setup_token(platform_url, token, machine_name)
+
+    new_agent_id = payload["agent"]["id"]
+    if new_agent_id != config.agent_id:
+        raise click.ClickException(
+            f"Token belongs to a different agent ({new_agent_id}) than this "
+            f"workspace ({config.agent_id}). Run 'cinna setup' in a new "
+            f"directory to register it."
+        )
+
+    config.cli_token = payload["cli_token"]
+    config.platform_url = payload["platform_url"]
+    if payload.get("frontend_url"):
+        config.frontend_url = payload["frontend_url"]
+    save_config(config, root)
+    upsert_agent_registry(
+        config.agent_id,
+        config.platform_url,
+        config.cli_token,
+        root,
+        frontend_url=config.frontend_url,
+    )
+    console.status(f"Token refreshed for agent: {config.agent_name}")
+
+
+def run_setup(setup_input: str, machine_name: str) -> None:
+    """Full setup flow — called by `cinna setup <token_or_url>`."""
+    total = 5
+
+    # Step 1: Authenticate
+    console.step(1, total, "Authenticating...")
+
+    platform_url, token = parse_setup_input(setup_input)
+    payload = _exchange_setup_token(platform_url, token, machine_name)
+    agent_info = payload["agent"]
+    agent_name = agent_info["name"]
+    dir_name = normalize_agent_dir_name(agent_name)
+    logger.info("Agent: %s (dir: %s)", agent_name, dir_name)
+
+    workspace_root = Path.cwd() / dir_name
+    if (workspace_root / ".cinna" / "config.json").exists():
+        raise click.ClickException(
+            f"Directory '{dir_name}/' already contains a cinna workspace.\n"
+            f"Remove it first with 'cinna disconnect' or delete the directory."
+        )
+    workspace_root.mkdir(exist_ok=True)
+
+    config = CinnaConfig(
+        platform_url=payload["platform_url"],
+        cli_token=payload["cli_token"],
+        agent_id=agent_info["id"],
+        agent_name=agent_name,
+        environment_id=agent_info["environment_id"],
+        template=agent_info["template"],
+        frontend_url=payload.get("frontend_url"),
+        knowledge_sources=[
+            KnowledgeSource(**ks) for ks in payload.get("knowledge_sources", [])
+        ],
+    )
+    save_config(config, workspace_root)
+    upsert_agent_registry(
+        config.agent_id,
+        config.platform_url,
+        config.cli_token,
+        workspace_root,
+        frontend_url=config.frontend_url,
+    )
+    console.status(f"Authenticated as agent: {agent_name}")
+
+    client = PlatformClient(config)
+    try:
+        # Step 2: Mutagen
+        console.step(2, total, "Checking Mutagen install...")
+        ensure_mutagen_ready(
+            client, config, workspace_root, interactive=sys.stdin.isatty()
+        )
+        console.status(f"Mutagen ready (version {config.mutagen_version})")
+
+        # Step 3: Initial clone
+        console.step(3, total, "Cloning workspace...")
+        ws_dir = workspace_dir(workspace_root)
+        ws_dir.mkdir(exist_ok=True)
+        try:
+            logger.info("Downloading workspace for agent %s", config.agent_id)
+            ws_tarball = client.download_workspace(config.agent_id)
+            logger.info("Workspace downloaded (%d bytes)", len(ws_tarball))
+            extract_workspace_tarball(ws_tarball, ws_dir)
+            console.status("Workspace cloned")
+        except Exception as e:
+            logger.warning("Workspace download failed: %s", e)
+            console.warn(f"Workspace download failed: {e}")
+            console.warn("Mutagen will reconcile on first sync start.")
+        ensure_workspace_dirs(ws_dir)
+
+        # Step 4: Context files + MCP config
+        console.step(4, total, "Configuring development environment...")
+        try:
+            building_ctx = client.get_building_context(config.agent_id)
+            generate_context_files(building_ctx, config, workspace_root)
+        except Exception as e:
+            logger.warning("Building context fetch failed: %s", e)
+            console.warn(f"Building context fetch failed: {e}")
+
+        generate_mcp_json(config, workspace_root)
+        generate_opencode_json(config, workspace_root)
+        generate_gitignore(workspace_root)
+
+        # Step 5: Start continuous sync (foreground — blocks until Ctrl-C)
+        console.step(5, total, "Starting continuous sync...")
+        sync_session.write_mutagen_yml(workspace_root)
+        sync_started = False
+        try:
+            sync_session.start(config, workspace_root)
+            sync_started = True
+            console.status("Sync session started")
+        except click.ClickException as e:
+            logger.warning("Sync start failed: %s", e.format_message())
+            console.warn(f"Sync start failed: {e.format_message()}")
+            console.warn("Run 'cinna dev' from the agent directory to retry.")
+
+        console.status("Setup complete!")
+        console.console.print()
+        console.console.print(f"  cd {dir_name}/")
+        console.console.print(
+            "  cinna dev                         # start a foreground dev session"
+        )
+        console.console.print(
+            "  claude                            # open Claude Code with MCP tools"
+        )
+        console.console.print(
+            "  cinna list                        # see all registered agents"
+        )
+        console.console.print(
+            "  cinna sync status                 # view sync state (from another terminal)"
+        )
+        console.console.print(
+            "  cinna exec python scripts/main.py # run a command in the remote env"
+        )
+        console.console.print()
+
+        # Attach the foreground sync TUI. Sync lives exactly as long as this
+        # process — Ctrl-C terminates the session so nothing is left dangling
+        # in the shared Mutagen daemon.
+        if sync_started:
+            console.status("Live sync attached — press Ctrl-C to stop.")
+            sync_session.run_foreground(config)
+            console.status("Sync session terminated.")
+    finally:
+        client.close()

cinna/client.py

@@ -0,0 +1,169 @@
+"""HTTP client for platform API. All backend communication goes through here."""
+
+import json
+import logging
+from typing import Iterator
+
+import httpx
+
+from cinna.config import CinnaConfig
+from cinna.auth import get_auth_headers
+from cinna.errors import AuthenticationError, PlatformError
+
+logger = logging.getLogger("cinna.client")
+
+DEFAULT_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+DOWNLOAD_TIMEOUT = httpx.Timeout(300.0, connect=10.0)
+# Exec streams can be long-running — disable read timeout so idle output doesn't abort.
+EXEC_STREAM_TIMEOUT = httpx.Timeout(None, connect=10.0)
+
+
+class PlatformClient:
+    """HTTP client wrapping httpx with CLI token authentication."""
+
+    def __init__(self, config: CinnaConfig):
+        self.config = config
+        self.base_url = config.platform_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=get_auth_headers(config),
+            timeout=DEFAULT_TIMEOUT,
+            follow_redirects=True,
+        )
+
+    def _handle_response(self, response: httpx.Response) -> httpx.Response:
+        """Check response status. Raise typed exceptions for known error codes."""
+        logger.debug(
+            "%s %s -> %s (%d bytes)",
+            response.request.method,
+            response.request.url,
+            response.status_code,
+            len(response.content),
+        )
+        if response.status_code == 401:
+            detail = ""
+            try:
+                detail = response.json().get("detail", "")
+            except Exception:
+                pass
+            logger.error("Authentication failed: %s", detail)
+            raise AuthenticationError(detail)
+        if response.status_code == 404:
+            logger.error("Resource not found: %s", response.request.url)
+            raise PlatformError(404, "Agent not found. It may have been deleted.")
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get("detail", response.text)
+            except Exception:
+                detail = response.text
+            logger.error(
+                "Platform error %s: %s (url: %s, body: %.500s)",
+                response.status_code,
+                detail,
+                response.request.url,
+                response.text,
+            )
+            raise PlatformError(response.status_code, detail)
+        return response
+
+    # --- Setup (no auth) ---
+
+    def exchange_setup_token(
+        self, token: str, machine_name: str, machine_info: str
+    ) -> dict:
+        """POST /api/cli-setup/{token} — exchange setup token for bootstrap payload."""
+        response = httpx.post(
+            f"{self.base_url}/api/cli-setup/{token}",
+            json={"machine_name": machine_name, "machine_info": machine_info},
+            timeout=DEFAULT_TIMEOUT,
+        )
+        return self._handle_response(response).json()
+
+    # --- Workspace (initial clone only; Mutagen owns it afterwards) ---
+
+    def download_workspace(self, agent_id: str) -> bytes:
+        """GET /api/v1/cli/agents/{id}/workspace — one-shot tarball for initial clone."""
+        response = self._client.get(
+            f"/api/v1/cli/agents/{agent_id}/workspace",
+            timeout=DOWNLOAD_TIMEOUT,
+        )
+        return self._handle_response(response).content
+
+    # --- Building Context ---
+
+    def get_building_context(self, agent_id: str) -> dict:
+        """GET /api/v1/cli/agents/{id}/building-context — assembled prompt + settings."""
+        response = self._client.get(
+            f"/api/v1/cli/agents/{agent_id}/building-context",
+            timeout=DOWNLOAD_TIMEOUT,
+        )
+        return self._handle_response(response).json()
+
+    # --- Knowledge ---
+
+    def search_knowledge(
+        self, agent_id: str, query: str, topic: str | None = None
+    ) -> dict:
+        """POST /api/v1/cli/agents/{id}/knowledge/search — search knowledge base."""
+        payload: dict = {"query": query}
+        if topic:
+            payload["topic"] = topic
+        response = self._client.post(
+            f"/api/v1/cli/agents/{agent_id}/knowledge/search",
+            json=payload,
+        )
+        return self._handle_response(response).json()
+
+    # --- Live Sync Runtime ---
+
+    def get_sync_runtime(self, agent_id: str) -> dict:
+        """GET /api/v1/cli/agents/{id}/sync-runtime — required Mutagen version + hash."""
+        response = self._client.get(
+            f"/api/v1/cli/agents/{agent_id}/sync-runtime",
+        )
+        return self._handle_response(response).json()
+
+    # --- Remote exec (SSE stream) ---
+
+    def stream_exec(self, agent_id: str, command: str) -> Iterator[dict]:
+        """POST /api/v1/cli/agents/{id}/exec — stream command output events.
+
+        Yields parsed event dicts. Known shapes:
+          {"type": "exec_id", "exec_id": "<uuid>"}
+          {"type": "tool_result_delta", "content": "...", "metadata": {...}}
+          {"type": "done", "exit_code": N, "duration_seconds": F}
+          {"type": "interrupted", "exit_code": -1}
+          {"type": "error", "content": "..."}
+
+        The caller is responsible for interpreting `done`/`interrupted` and
+        mapping to a process exit code.
+        """
+        url = f"/api/v1/cli/agents/{agent_id}/exec"
+        payload = {"command": command}
+        with self._client.stream(
+            "POST", url, json=payload, timeout=EXEC_STREAM_TIMEOUT
+        ) as response:
+            if response.status_code >= 400:
+                # Read the body so _handle_response can surface the error.
+                response.read()
+                self._handle_response(response)
+                return
+
+            for line in response.iter_lines():
+                if not line:
+                    continue
+                if line.startswith("data: "):
+                    data_str = line[6:]
+                    try:
+                        yield json.loads(data_str)
+                    except json.JSONDecodeError:
+                        logger.warning("Could not parse SSE event: %s", data_str[:200])
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

cinna/config.py

@@ -0,0 +1,193 @@
+"""Manages .cinna/config.json — the single source of truth for CLI state."""
+
+import json
+import os
+import threading
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+
+from cinna.errors import ConfigNotFoundError
+
+CONFIG_DIR = ".cinna"
+CONFIG_FILE = "config.json"
+BUILD_DIR = "build"
+
+# Global per-user state — lives outside any single workspace so that one
+# Mutagen daemon can serve multiple agent syncs concurrently. The SSH shim
+# reads `agents.json` to resolve the CLI token / platform URL for whichever
+# agent Mutagen is asking it to connect to on each invocation.
+GLOBAL_STATE_DIR = Path.home() / ".cinna"
+AGENTS_REGISTRY_FILE = "agents.json"
+
+
+@dataclass
+class KnowledgeSource:
+    id: str
+    name: str
+    topics: list[str]
+
+
+@dataclass
+class CinnaConfig:
+    platform_url: str
+    cli_token: str
+    agent_id: str
+    agent_name: str
+    environment_id: str
+    template: str
+    # User-facing frontend URL (the platform's web UI). Set by the bootstrap
+    # exchange response; falls back to ``platform_url`` for backwards compat
+    # with configs written before this field existed.
+    frontend_url: str | None = None
+    knowledge_sources: list[KnowledgeSource] = field(default_factory=list)
+    mutagen_version: str | None = None
+    last_sync_runtime_check_at: str | None = None
+    last_sync_connected_at: str | None = None
+
+
+def find_workspace_root(start: Path | None = None) -> Path:
+    """Walk up from start (or cwd) looking for .cinna/config.json.
+
+    Returns the workspace root directory (parent of .cinna/).
+    Raises ConfigNotFoundError if not found.
+    """
+    current = (start or Path.cwd()).resolve()
+    while True:
+        if (current / CONFIG_DIR / CONFIG_FILE).is_file():
+            return current
+        parent = current.parent
+        if parent == current:
+            raise ConfigNotFoundError()
+        current = parent
+
+
+def load_config(workspace_root: Path | None = None) -> CinnaConfig:
+    """Load and validate config from .cinna/config.json."""
+    if workspace_root is None:
+        workspace_root = find_workspace_root()
+    config_path = workspace_root / CONFIG_DIR / CONFIG_FILE
+    if not config_path.is_file():
+        raise ConfigNotFoundError()
+    data = json.loads(config_path.read_text())
+    ks_list = [KnowledgeSource(**ks) for ks in data.pop("knowledge_sources", [])]
+    # Tolerate legacy fields (e.g. container_name from pre-live-sync configs).
+    known_fields = {f for f in CinnaConfig.__dataclass_fields__ if f != "knowledge_sources"}
+    data = {k: v for k, v in data.items() if k in known_fields}
+    return CinnaConfig(**data, knowledge_sources=ks_list)
+
+
+def save_config(config: CinnaConfig, workspace_root: Path) -> None:
+    """Write config to .cinna/config.json."""
+    cfg_dir = workspace_root / CONFIG_DIR
+    cfg_dir.mkdir(parents=True, exist_ok=True)
+    data = asdict(config)
+    (cfg_dir / CONFIG_FILE).write_text(json.dumps(data, indent=2) + "\n")
+
+
+def config_dir(workspace_root: Path) -> Path:
+    """Return path to .cinna/ directory."""
+    return workspace_root / CONFIG_DIR
+
+
+def workspace_dir(workspace_root: Path) -> Path:
+    """Return path to workspace/ directory."""
+    return workspace_root / "workspace"
+
+
+def build_dir(workspace_root: Path) -> Path:
+    """Return path to .cinna/build/ directory.
+
+    Historically held the Docker build context. In live-sync mode the directory
+    is usually absent; the helper is retained so any prompt reference docs that
+    do land there continue to be discovered.
+    """
+    return config_dir(workspace_root) / BUILD_DIR
+
+
+# ── Global agent registry ────────────────────────────────────────────────
+#
+# `~/.cinna/agents.json` maps agent_id → {platform_url, cli_token,
+# workspace_path}. The SSH shim reads this on every Mutagen SSH invocation
+# to resolve per-agent credentials; needed because a single Mutagen daemon
+# serves SSH subprocesses for every agent the user has synced, and the
+# daemon's own env is captured once at start.
+
+_registry_lock = threading.Lock()
+
+
+def agents_registry_path() -> Path:
+    return GLOBAL_STATE_DIR / AGENTS_REGISTRY_FILE
+
+
+def _read_registry() -> dict:
+    path = agents_registry_path()
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_registry(data: dict) -> None:
+    path = agents_registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    # Restrict perms: the file holds long-lived CLI JWTs.
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    tmp.replace(path)
+
+
+def upsert_agent_registry(
+    agent_id: str,
+    platform_url: str,
+    cli_token: str,
+    workspace_path: Path,
+    frontend_url: str | None = None,
+) -> None:
+    """Register or refresh an agent's credentials in the global registry.
+
+    ``frontend_url`` is optional for backwards compatibility with callers
+    written before the field existed; ``cinna list`` will fall back to
+    ``platform_url`` when it's missing.
+    """
+    with _registry_lock:
+        data = _read_registry()
+        entry = {
+            "platform_url": platform_url,
+            "cli_token": cli_token,
+            "workspace_path": str(workspace_path),
+        }
+        if frontend_url:
+            entry["frontend_url"] = frontend_url
+        data[agent_id] = entry
+        _write_registry(data)
+
+
+def remove_agent_registry(agent_id: str) -> None:
+    """Drop an agent's entry. No-op if it wasn't present."""
+    with _registry_lock:
+        data = _read_registry()
+        if agent_id in data:
+            del data[agent_id]
+            _write_registry(data)
+
+
+def lookup_agent_registry(agent_id: str) -> dict | None:
+    """Return the registry entry for an agent, or None."""
+    return _read_registry().get(agent_id)
+
+
+def list_agent_registry() -> list[dict]:
+    """Return every registered agent as a list of dicts, sorted by agent_id.
+
+    Each entry contains ``agent_id`` plus the registry fields
+    (``platform_url``, ``cli_token``, ``workspace_path``).
+    """
+    registry = _read_registry()
+    return [{"agent_id": aid, **entry} for aid, entry in sorted(registry.items())]