contree-mcp 0.1.0__py3-none-any.whl

contree_mcp/backend_types.py

@@ -0,0 +1,301 @@
+"""Backend types for Contree MCP DO NOT EDIT THIS FILE UNLESS YOU KNOW WHAT YOU ARE DOING"""
+
+from base64 import b64decode, b64encode
+from enum import Enum
+from typing import Any, Literal, TypeVar
+from uuid import UUID
+
+from pydantic import BaseModel, ByteSize, Field, PositiveInt, model_validator
+from typing_extensions import Self
+
+PublicUUID = str(UUID(int=0))
+
+E = TypeVar("E", bound=Enum)
+
+
+class ImageCredentials(BaseModel):
+    username: str = ""
+    password: str = ""
+
+
+class ImageRegistry(BaseModel):
+    url: str
+    credentials: ImageCredentials = ImageCredentials()
+
+
+class ImportImageMetadata(BaseModel):
+    registry: ImageRegistry
+    tag: str | None = None
+    timeout: PositiveInt = 300
+
+
+class ImageSize(BaseModel):
+    physical: int = -1
+    logical: int = -1
+
+
+class Image(BaseModel):
+    """Response model for image endpoints.
+
+    API handlers:
+    - GET /inspect/{image_uuid}/ -> Image
+    - GET /inspect/?tag={tag} -> Image (redirect)
+    - PATCH /images/{image_uuid}/tag -> Image
+    - DELETE /images/{image_uuid}/tag -> Image
+    """
+
+    uuid: str = Field(description="Image UUID")
+    tag: str | None = Field(default=None, description="Image tag or null")
+    created_at: str = Field(default="", description="ISO 8601 creation timestamp")
+
+
+class ImageListResponse(BaseModel):
+    """Response from GET /images.
+
+    API handlers:
+    - GET /images -> ImageListResponse
+    """
+
+    images: list[Image] = Field(default_factory=list)
+
+
+class FileItem(BaseModel):
+    """File info in directory listing."""
+
+    path: str = Field(description="File name relative to directory")
+    size: int = Field(description="File size in bytes")
+    owner: int | str = Field(description="User ID or name of owner")
+    group: int | str = Field(description="Group ID or name")
+    mode: int = Field(description="File permissions as integer")
+    mtime: int = Field(description="Last modification Unix timestamp")
+    is_dir: bool = Field(description="Directory indicator")
+    is_regular: bool = Field(description="Regular file indicator")
+    is_symlink: bool = Field(description="Symbolic link indicator")
+    is_socket: bool = Field(description="Socket indicator")
+    is_fifo: bool = Field(description="FIFO/named pipe indicator")
+    symlink_to: str = Field(default="", description="Target path for symlinks")
+
+
+class DirectoryList(BaseModel):
+    """Response from GET /inspect/{uuid}/list.
+
+    API handlers:
+    - GET /inspect/{image_uuid}/list -> DirectoryList
+    """
+
+    path: str = Field(description="Directory path listed")
+    files: list[FileItem] = Field(default_factory=list)
+
+
+class FileResponse(BaseModel):
+    """Response from file endpoints.
+
+    API handlers:
+    - POST /files -> FileResponse
+    - GET /files?sha256={hash} -> FileResponse
+    """
+
+    uuid: str = Field(description="File UUID")
+    sha256: str = Field(description="SHA256 hash of file content")
+
+
+class InstanceSpawnResponse(BaseModel):
+    """Response from POST /instances.
+
+    API handlers:
+    - POST /instances -> InstanceSpawnResponse
+    - POST /images/import -> InstanceSpawnResponse (same format)
+    """
+
+    uuid: str = Field(description="Operation UUID")
+
+
+class Stream(BaseModel):
+    value: str
+    encoding: Literal["ascii", "base64"] = "ascii"
+    truncated: bool = False
+
+    def text(self) -> str:
+        if self.encoding == "ascii":
+            return self.value
+        elif self.encoding == "base64":
+            return b64decode(self.value).decode("utf-8", errors="replace")
+        raise ValueError(f"Unsupported encoding: {self.encoding}")
+
+    @classmethod
+    def from_bytes(cls, data: bytes, max_size: int = -1) -> Self:
+        encoding: Literal["ascii", "base64"]
+        truncated = False
+        if 0 < max_size < len(data):
+            data = data[:max_size]
+            truncated = True
+        try:
+            encoding = "ascii"
+            value = data.decode("ascii")
+        except UnicodeDecodeError:
+            encoding = "base64"
+            value = b64encode(data).decode("ascii")
+        return cls(value=value, encoding=encoding, truncated=truncated)
+
+    def to_bytes(self) -> bytes:
+        match self.encoding:
+            case "ascii":
+                return self.value.encode("ascii")
+            case "base64":
+                return b64decode(self.value)
+            case _:
+                raise ValueError(f"Unsupported encoding: {self.encoding}")
+
+    def __bool__(self) -> bool:
+        return bool(self.value)
+
+
+class ConsumedResources(BaseModel):
+    block_input: int = -1
+    block_output: int = -1
+    cost: float = -1.0
+    elapsed_time: float = -1
+    involuntary_switches: int = -1
+    max_rss: int = -1
+    monotonic_time: float = -1
+    page_faults: int = -1
+    page_faults_io: int = -1
+    shared_memory: int = -1
+    signals: int = -1
+    swaps: int = -1
+    system_cpu_time: float = -1.0
+    unshared_memory: int = -1
+    user_cpu_time: float = -1.0
+    voluntary_switches: int = -1
+
+
+class ProcessExitState(BaseModel):
+    continued: bool = False
+    core_dump: bool = False
+    exit_code: int = 0
+    pid: int = 0
+    signal: int = -1
+    stopped: bool = False
+    timed_out: bool = False
+
+
+class InstanceResult(BaseModel):
+    resources: ConsumedResources = ConsumedResources()
+    state: ProcessExitState = ProcessExitState()
+    stdout: Stream
+    stderr: Stream
+
+
+class InstanceFileSpec(BaseModel):
+    uuid: str
+    mode: str = "0644"
+    uid: int = 0
+    gid: int = 0
+
+
+class InstanceMetadata(BaseModel):
+    """Metadata for instance execution operations"""
+
+    command: str = Field(description="Command to run")
+    image: str = Field(description="Image UUID or string starts with 'tag:'")
+    hostname: str = "linuxkit"
+    args: list[str] = Field(default_factory=list, description="Command arguments, must be used with shell is false")
+    shell: bool = Field(default=False, description="In this mode command is a shell expression and args must be empty")
+    env: dict[str, str] = Field(default_factory=dict)
+    cwd: str = Field(default="/root", description="Path to the working directory, must be absolute")
+    disposable: bool = False
+    stdin: Stream = Stream(value="")
+    timeout: PositiveInt = 60
+    truncate_output_at: ByteSize = ByteSize(64 * 1024)
+    files: dict[str, InstanceFileSpec] = Field(default_factory=dict, description="Files to add to the image")
+    result: InstanceResult | None = None
+
+
+class OperationStatus(str, Enum):
+    PENDING = "PENDING"
+    EXECUTING = "EXECUTING"
+    SUCCESS = "SUCCESS"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    ASSIGNED = "ASSIGNED"
+
+    def is_terminal(self) -> bool:
+        cls = self.__class__
+        return self in {cls.SUCCESS, cls.FAILED, cls.CANCELLED}
+
+
+class OperationKind(str, Enum):
+    INSTANCE = "instance"
+    IMAGE_IMPORT = "image_import"
+
+
+class OperationResult(BaseModel):
+    image: str | None = Field(default=None, description="Result image UUID or null")
+    tag: str | None = Field(default=None, description="Assigned tag or null")
+
+
+class OperationSummary(BaseModel):
+    """Summary model for operations in list.
+
+    API handlers:
+    - GET /operations -> OperationListResponse.operations (list of OperationSummary)
+    """
+
+    uuid: str = Field(description="Operation UUID")
+    kind: OperationKind = Field(description="Operation kind")
+    status: OperationStatus = Field(description="Operation status")
+    error: str | None = Field(default=None, description="Error message if failed")
+    created_at: str = Field(default="", description="ISO 8601 creation timestamp")
+
+
+class OperationListResponse(BaseModel):
+    """Response from GET /operations.
+
+    API handlers:
+    - GET /operations -> OperationListResponse
+    """
+
+    operations: list[OperationSummary] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def wrap_list(cls, data: Any) -> Any:
+        """Handle backend returning list instead of dict with operations key."""
+        if isinstance(data, list):
+            return {"operations": data}
+        return data
+
+
+class OperationResponse(BaseModel):
+    """Response model for operation detail endpoint.
+
+    API handlers:
+    - GET /operations/{operation_id} -> OperationResponse
+    """
+
+    uuid: str = Field(default="", description="Operation UUID")
+    status: OperationStatus = Field(description="Operation status")
+    kind: OperationKind = Field(description="Operation kind")
+    error: str | None = Field(default=None, description="Error message if any")
+    metadata: InstanceMetadata | ImportImageMetadata | None = Field(default=None, description="Operation metadata")
+    result: OperationResult | None = Field(default=None, description="Operation result")
+    duration: float = Field(default=0.0, description="Operation duration")
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_metadata(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "kind" in data:
+            data = dict(data)  # Create mutable copy
+            data["kind"] = data["kind"].lower()
+        return data
+
+
+class CancelOperationResponse(BaseModel):
+    """Response from cancel operation endpoint.
+
+    API handlers:
+    - DELETE /operations/{operation_id} -> CancelOperationResponse
+    """
+
+    uuid: str = Field(default="", description="Operation UUID")
+    status: OperationStatus = Field(default=OperationStatus.CANCELLED)

contree_mcp/cache.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import sqlite3
+from collections.abc import Mapping
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+import aiosqlite
+from pydantic import BaseModel
+
+# Pattern: alphanumeric, underscore, dot (for nested paths like "user.name")
+SAFE_FIELD_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_.]*$")
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    id: int
+    kind: str
+    key: str
+    parent_id: int | None  # Reference to parent entry's id
+    data: Mapping[str, Any]
+    created_at: datetime
+    updated_at: datetime
+
+    @classmethod
+    def from_row(cls, cursor: sqlite3.Cursor, row: tuple[Any, ...]) -> CacheEntry:
+        row_dict: dict[str, Any] = {col[0]: row[idx] for idx, col in enumerate(cursor.description or [])}
+        row_dict["data"] = MappingProxyType(json.loads(row_dict["data"]))
+        return cls(**row_dict)
+
+
+class Cache:
+    DEFAULT_CACHE_DIR = Path.home() / ".cache" / "contree_mcp"
+    DEFAULT_CACHE_DB_PATH = DEFAULT_CACHE_DIR / "cache.db"
+
+    SCHEMA = """
+         CREATE TABLE IF NOT EXISTS cache (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            kind TEXT NOT NULL,
+            key TEXT NOT NULL,
+            parent_id INTEGER,
+            data TEXT NOT NULL,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+            UNIQUE(kind, key),
+            FOREIGN KEY (parent_id) REFERENCES cache(id)
+         );
+         CREATE INDEX IF NOT EXISTS idx_cache_kind ON cache(kind);
+         CREATE INDEX IF NOT EXISTS idx_cache_parent ON cache(parent_id);
+         CREATE INDEX IF NOT EXISTS idx_cache_created ON cache(created_at);
+    """
+
+    def __init__(self, db_path: Path = DEFAULT_CACHE_DB_PATH, retention_days: int = 120) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.retention_days = retention_days
+        self.__conn: aiosqlite.Connection | None = None
+        self.__lock = asyncio.Lock()
+        self.__retention_task: asyncio.Task[None] | None = None
+
+    @property
+    def conn(self) -> aiosqlite.Connection:
+        """Get the database connection (sync wrapper)."""
+        if self.__conn is None:
+            raise RuntimeError("Database connection not initialized. Use 'async with' context.")
+        return self.__conn
+
+    async def _init_db(self) -> None:
+        async with self.__lock:
+            if self.__conn is not None:
+                raise RuntimeError("Database already initialized.")
+
+            conn = await aiosqlite.connect(str(self.db_path))
+            await conn.execute("PRAGMA journal_mode=WAL")
+            conn.row_factory = CacheEntry.from_row  # type: ignore[assignment]
+            await conn.executescript(self.SCHEMA)
+            await conn.commit()
+            self.__conn = conn
+            self.__retention_task = asyncio.create_task(self.retain_periodically())
+
+    async def retain_periodically(self, interval_hours: int = 24) -> None:
+        await self._retain()
+        while True:
+            await asyncio.sleep(interval_hours * 3600)
+            with suppress(Exception):
+                await self._retain()
+
+    async def _retain(self) -> None:
+        if self.retention_days <= 0:
+            return
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=self.retention_days)).isoformat()
+        await self.conn.execute("DELETE FROM cache WHERE created_at < ?", (cutoff,))
+        await self.conn.commit()
+
+    async def close(self) -> None:
+        async with self.__lock:
+            if self.__conn is None:
+                return
+            await self.__conn.close()
+            if self.__retention_task is not None:
+                self.__retention_task.cancel()
+                await asyncio.gather(self.__retention_task, return_exceptions=True)
+            self.__conn = None
+
+    async def __aenter__(self) -> Cache:
+        await self._init_db()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def get(self, kind: str, key: str, ttl: int | float = -1) -> CacheEntry | None:
+        async with self.conn.execute("""SELECT * FROM cache WHERE kind = ? AND key = ?""", (kind, key)) as cursor:
+            result = await cursor.fetchone()
+
+        if result is None:
+            return None
+
+        if ttl > 0 and isinstance(result, CacheEntry):
+            age = (datetime.now(timezone.utc) - result.updated_at).total_seconds()
+            if age > ttl:
+                return None
+        return result  # type: ignore[return-value]
+
+    async def put(
+        self, kind: str, key: str, data: dict[str, Any] | BaseModel, parent_id: int | None = None
+    ) -> CacheEntry:
+        if isinstance(data, BaseModel):
+            data = data.model_dump(mode="json")
+
+        await self.conn.execute(
+            """
+            INSERT INTO cache (kind, key, parent_id, data, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(kind, key) DO UPDATE
+            SET parent_id=excluded.parent_id, data=excluded.data, updated_at=excluded.updated_at
+            """,
+            (kind, key, parent_id, json.dumps(data), datetime.now(timezone.utc)),
+        )
+        await self.conn.commit()
+        entry = await self.get(kind, key)
+        if entry is None:
+            raise RuntimeError("Failed to retrieve cache entry after insertion.")
+        return entry
+
+    async def delete(self, kind: str, key: str) -> bool:
+        cursor = await self.conn.execute("DELETE FROM cache WHERE kind = ? AND key = ?", (kind, key))
+        await self.conn.commit()
+        return cursor.rowcount > 0
+
+    async def list_entries(self, kind: str, limit: int = 100, **field_filter: Any) -> list[CacheEntry]:
+        # Validate filter keys to prevent SQL injection
+        for key in field_filter:
+            if not SAFE_FIELD_PATTERN.match(key):
+                raise ValueError(f"Invalid filter field name: {key!r}")
+
+        json_filter = list(field_filter.items())
+        json_query = " AND ".join([f"json_extract(data, '$.{k}') = ?" for k, _ in json_filter])
+        if json_query:
+            json_query = f" AND {json_query}"
+        json_params = tuple(v for _, v in json_filter)
+        query = f"""SELECT * FROM cache WHERE kind = ? {json_query} ORDER BY created_at DESC LIMIT ?"""
+        params = (kind, *json_params, limit)
+        async with self.conn.execute(query, params) as cursor:
+            return await cursor.fetchall()  # type: ignore[return-value]
+
+    async def get_by_id(self, entry_id: int) -> CacheEntry | None:
+        async with self.conn.execute("""SELECT * FROM cache WHERE id = ?""", (entry_id,)) as cursor:
+            return await cursor.fetchone()  # type: ignore[return-value]
+
+    async def get_ancestors(self, kind: str, key: str, limit: int = 50) -> list[CacheEntry]:
+        query = """
+            WITH RECURSIVE ancestor_chain(id, kind, key, parent_id, data, created_at, updated_at, depth) AS
+                (
+                    SELECT *, 0 FROM cache WHERE kind = ? AND key = ?
+                    UNION ALL
+                    SELECT c.*, ac.depth + 1 FROM cache c
+                      INNER JOIN ancestor_chain ac ON c.id = ac.parent_id WHERE ac.depth < ?
+                )
+            SELECT id, kind, key, parent_id, data, created_at, updated_at
+            FROM ancestor_chain WHERE depth > 0 ORDER BY depth
+        """
+        async with self.conn.execute(query, (kind, key, limit)) as cursor:
+            return await cursor.fetchall()  # type: ignore[return-value]
+
+    async def get_children(self, kind: str, parent_key: str, limit: int = 50) -> list[CacheEntry]:
+        parent = await self.get(kind, parent_key)
+        if parent is None:
+            return []
+
+        query = """
+            WITH RECURSIVE child_chain(id, kind, key, parent_id, data, created_at, updated_at) AS (
+                SELECT * FROM cache WHERE parent_id = ?
+                UNION ALL
+                SELECT c.* FROM cache c INNER JOIN child_chain cc ON c.parent_id = cc.id
+            )
+            SELECT * FROM child_chain LIMIT ?
+        """
+
+        async with self.conn.execute(query, (parent.id, limit)) as cursor:
+            return await cursor.fetchall()  # type: ignore[return-value]