mlspace-plugin 0.2.1__py3-none-any.whl

mlspace_mcp/client_setup.py

@@ -0,0 +1,235 @@
+"""User-scoped client registration and packaged skill installation."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .config import user_config_file
+from .jsonc import loads as load_jsonc
+from .jsonc import set_member as set_jsonc_member
+
+CLIENTS = {'claude-code': 'claude', 'codex': 'codex', 'opencode': 'opencode'}
+
+
+def detect_clients() -> dict[str, str]:
+    return {name: path for name, executable in CLIENTS.items()
+            if (path := shutil.which(executable))}
+
+
+def server_command() -> list[str]:
+    source = Path(__file__).resolve()
+    # Package-index installs may run inside an evictable `uvx` environment.
+    # Pin the runtime to the skills version, never to a cache directory or latest.
+    cached = any(re.fullmatch(r'archive-v\d+', part) for part in source.parts)
+    if cached and 'site-packages' in source.parts and (uvx := shutil.which('uvx')):
+        if any(source.parent.parent.glob('mlspace_plugin-*.dist-info/direct_url.json')):
+            raise ValueError('For a local wheel, use `uv tool install /path/to/package.whl` '
+                             'before setup, or use setup --config-only for a native plugin.')
+        return [uvx, '--from', f'mlspace-plugin=={__version__}',
+                'mlspace-plugin', '--transport', 'stdio']
+    executable = Path(sys.executable).parent / 'mlspace-plugin'
+    if not executable.is_file():
+        raise ValueError('Install the package with `uv tool install .` before connecting clients.')
+    # An editable installation under /tmp disappears on reboot; reject that source.
+    if source.is_relative_to(Path(tempfile.gettempdir()).resolve()) or str(source).startswith('/tmp/'):
+        raise ValueError('Temporary installation: install the wheel with `uv tool install` first.')
+    return [str(executable.absolute()), '--transport', 'stdio']
+
+
+def atomic_write(path: Path, text: str, mode: int = 0o600) -> None:
+    if path.is_symlink():
+        raise ValueError(f'Refusing to replace a symlink: {path}')
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, name = tempfile.mkstemp(prefix='.' + path.name, dir=path.parent)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+            os.fchmod(stream.fileno(), mode)
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+def _skill_sources() -> dict[str, str]:
+    bundled = files('mlspace_mcp').joinpath('skills')
+    # Editable installs use the very same versioned source that goes into the wheel.
+    source = Path(__file__).resolve().parents[2] / 'plugin/skills'
+    root = bundled if bundled.is_dir() else source
+    result = {item.name: item.joinpath('SKILL.md').read_text(encoding='utf-8')
+              for item in root.iterdir() if item.is_dir() and item.joinpath('SKILL.md').is_file()}
+    if not result:
+        raise ValueError('No packaged skills found; reinstall the MLSpace wheel.')
+    return result
+
+
+def _hash(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def _config(client: str) -> Path:
+    if client == 'claude-code':
+        custom = os.environ.get('CLAUDE_CONFIG_DIR')
+        return Path(custom) / '.claude.json' if custom else Path.home() / '.claude.json'
+    if client == 'codex':
+        return Path(os.environ.get('CODEX_HOME', str(Path.home() / '.codex'))) / 'config.toml'
+    explicit = os.environ.get('OPENCODE_CONFIG')
+    if explicit:
+        return Path(explicit).expanduser().absolute()
+    root = Path(os.environ.get('XDG_CONFIG_HOME', str(Path.home() / '.config'))) / 'opencode'
+    jsonc, plain = root / 'opencode.jsonc', root / 'opencode.json'
+    if jsonc.exists() and plain.exists():
+        raise ValueError('Both opencode.json and opencode.jsonc exist; select OPENCODE_CONFIG explicitly.')
+    return jsonc if jsonc.exists() else plain
+
+
+def _read_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    if path.suffix == '.toml':
+        if sys.version_info >= (3, 11):
+            import tomllib
+        else:
+            import tomli as tomllib
+        return dict(tomllib.loads(path.read_text()))
+    return load_jsonc(path.read_text())
+
+
+def prepare_clients(clients: dict[str, str], env_file: Path, command: list[str]) -> dict[str, Any]:
+    """Plan all writes and reject conflicts before setup saves credentials."""
+    state_path = user_config_file().parent / 'install-state.json'
+    state = json.loads(state_path.read_text()) if state_path.exists() else {}
+    sources = _skill_sources()
+    writes: dict[Path, str] = {}
+    registrations = []
+    for client, executable in clients.items():
+        if client not in CLIENTS:
+            raise ValueError('Unknown client: ' + client)
+        config = _config(client)
+        if config.is_symlink():
+            raise ValueError(f'Client config is a symlink; configure it manually: {config}')
+        data = _read_config(config)
+        key = {'claude-code': 'mcpServers', 'codex': 'mcp_servers', 'opencode': 'mcp'}[client]
+        entries = data.get(key, {})
+        if not isinstance(entries, dict):
+            raise ValueError(f'Invalid MCP configuration: {config}')
+        for name, entry in entries.items():
+            if name != 'mlspace' and ('mlspace' in name.lower() or 'mlspace-plugin' in json.dumps(entry)):
+                raise ValueError(f'Existing MLSpace integration {name} in {config}; migrate it first.')
+        # Enabled native plugins can register a second server and duplicate skills.
+        settings = Path(os.environ.get('CLAUDE_CONFIG_DIR', str(Path.home() / '.claude'))) / 'settings.json'
+        plugin_data = _read_config(settings) if client == 'claude-code' else data
+        plugins = plugin_data.get('enabledPlugins', plugin_data.get('plugins', {}))
+        if isinstance(plugins, dict) and any('mlspace' in name.lower() and
+                                            (value.get('enabled', True) if isinstance(value, dict) else value) is not False
+                                            for name, value in plugins.items()):
+            raise ValueError(f'Existing MLSpace plugin in {client}; disable or migrate it first.')
+        entry = ({'type': 'local', 'command': command,
+                  'environment': {'MLSPACE_ENV_FILE': str(env_file.absolute())}, 'enabled': True}
+                 if client == 'opencode' else
+                 {'command': command[0], 'args': command[1:],
+                  'env': {'MLSPACE_ENV_FILE': str(env_file.absolute())}})
+        current = entries.get('mlspace')
+        previous = state.get('clients', {}).get(client)
+        if current is not None:
+            comparable = dict(current)
+            comparable.pop('type', None) if client != 'opencode' else None
+            if comparable != entry and _hash(json.dumps(current, sort_keys=True)) != previous:
+                raise ValueError(f'Existing mlspace entry differs in {config}; it was not overwritten.')
+        registrations.append((client, executable, config, entry, current))
+        skills_root = (Path(os.environ.get('CLAUDE_CONFIG_DIR', str(Path.home() / '.claude'))) / 'skills'
+                       if client == 'claude-code' else Path.home() / '.agents/skills')
+        for name, content in sources.items():
+            target = skills_root / name / 'SKILL.md'
+            if client == 'opencode':
+                # OpenCode discovers these shared locations; reuse an existing skill.
+                roots = [Path(os.environ.get('XDG_CONFIG_HOME', str(Path.home() / '.config'))) / 'opencode/skills',
+                         Path.home() / '.claude/skills', Path.home() / '.agents/skills']
+                existing = [root / name / 'SKILL.md' for root in roots
+                            if (root / name / 'SKILL.md').exists() or root / name / 'SKILL.md' in writes]
+                if existing:
+                    for candidate in existing:
+                        content_now = writes[candidate] if candidate in writes else candidate.read_text()
+                        if content_now != content and state.get('skills', {}).get(str(candidate)) != _hash(content_now):
+                            raise ValueError(f'Existing skill has local changes: {candidate}')
+                    target = existing[0]
+            if target.is_symlink() or target.parent.is_symlink():
+                if target.is_file() and target.read_text() == content:
+                    continue
+                raise ValueError(f'Existing skill symlink differs: {target}')
+            if target.exists() and target.read_text() != content:
+                if state.get('skills', {}).get(str(target)) != _hash(target.read_text()):
+                    raise ValueError(f'Existing skill has local changes: {target}')
+            writes[target] = content
+    return {'state_path': state_path, 'state': state, 'writes': writes,
+            'registrations': registrations}
+
+
+def install_clients(clients: dict[str, str], env_file: Path, command: list[str]) -> list[str]:
+    # Revalidate after human input: files may have changed since the preflight.
+    plan = prepare_clients(clients, env_file, command)
+    state, state_path = plan['state'], plan['state_path']
+    clean_env = {key: value for key, value in os.environ.items()
+                 if not key.startswith('MLSPACE_')}
+    installed = []
+    for client, executable, config, entry, current in plan['registrations']:
+        try:
+            if client == 'opencode':
+                text = config.read_text() if config.exists() else '{}\n'
+                updated = set_jsonc_member(text, ['mcp', 'mlspace'], entry)
+                if updated != text:
+                    atomic_write(config, updated)
+            else:
+                comparable = dict(current or {})
+                comparable.pop('type', None)
+                if current is not None and comparable != entry:
+                    # Preflight verified this is our unmodified registration.
+                    remove = [executable, 'mcp', 'remove', 'mlspace']
+                    if client == 'claude-code':
+                        remove += ['--scope', 'user']
+                    subprocess.run(remove, env=clean_env, check=True,
+                                   capture_output=True, timeout=30)
+                if comparable != entry:
+                    arguments = ([executable, 'mcp', 'add', 'mlspace', '--scope', 'user', '--transport', 'stdio',
+                                  '--env', 'MLSPACE_ENV_FILE=' + str(env_file.absolute())]
+                                 if client == 'claude-code' else
+                                 [executable, 'mcp', 'add', 'mlspace', '--env',
+                                  'MLSPACE_ENV_FILE=' + str(env_file.absolute())])
+                    subprocess.run(arguments + ['--', *command], env=clean_env, check=True,
+                                   capture_output=True, timeout=30)
+            saved = _read_config(config).get({'claude-code':'mcpServers', 'codex':'mcp_servers',
+                                             'opencode':'mcp'}[client], {}).get('mlspace')
+            comparable_saved = dict(saved) if isinstance(saved, dict) else {}
+            if client != 'opencode':
+                comparable_saved.pop('type', None)
+            if comparable_saved != entry:
+                raise ValueError(f'Client registration could not be confirmed for {client}; retry setup.')
+            state.setdefault('clients', {})[client] = _hash(json.dumps(saved, sort_keys=True))
+            atomic_write(state_path, json.dumps(state, indent=2))
+            installed.append(client)
+        except (subprocess.SubprocessError, OSError) as exc:
+            raise ValueError(f'Could not register {client}. Already registered: '
+                             f'{", ".join(installed) or "none"}. Retry setup; details suppressed '
+                             'because client output can contain secrets.') from exc
+    try:
+        for target, content in plan['writes'].items():
+            if not target.exists() or target.read_text() != content:
+                atomic_write(target, content, 0o644)
+            state.setdefault('skills', {})[str(target)] = _hash(content)
+            atomic_write(state_path, json.dumps(state, indent=2))
+    except (OSError, ValueError) as exc:
+        raise ValueError(f'MCP registered: {", ".join(installed)}. Skill installation incomplete; '
+                         'check permissions in the skills directory and rerun setup --force. '
+                         'Previous credentials have not been replaced.') from exc
+    return installed

mlspace_mcp/config.py

@@ -0,0 +1,283 @@
+"""Runtime settings, loaded from the ``MLSPACE_`` environment / ``.env``."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1", "0:0:0:0:0:0:0:1"}
+DEFAULT_BASE_URL = "https://api.ai.cloud.ru"
+LITERAL_DOTENV_MARKER = "# mlspace-plugin: literal-dotenv-v1"
+
+#: Absolute path of the credentials file, when the caller names one instead of
+#: relying on the search order below. The Agent Plugins bundle sets it to
+#: ``${PLUGIN_DATA}/.env`` — a path, not a secret, so it may travel in the package.
+ENV_FILE_VAR = "MLSPACE_ENV_FILE"
+
+#: What a hand-written credentials file needs. The workspace x-api-key is optional:
+#: when absent the server fetches it with the service-account token.
+CREDENTIALS = ("CLIENT_ID", "CLIENT_SECRET", "WORKSPACE_ID")
+
+APP_DIR = "mlspace-plugin"
+INIT_HINT = "run `mlspace-plugin setup` to fill it in"
+
+
+def user_config_file() -> Path:
+    """``~/.config/mlspace-plugin/.env`` — the one place a person configures once.
+
+    Honours ``XDG_CONFIG_HOME``. This is where ``mlspace-plugin setup`` writes, so the
+    same credentials serve every way the server gets launched: through the plugin
+    bundle, from a hand-written client config, or straight from a shell.
+    """
+    base = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    root = Path(base) if base else Path.home() / ".config"
+    return root / APP_DIR / ".env"
+
+
+def credential_files() -> list[Path]:
+    """The files consulted, in ASCENDING priority — the more specific, the later.
+
+    ``pydantic-settings`` lets the last file win and skips ones that do not exist,
+    so this is the whole precedence rule:
+
+    1. the user config — written by ``setup``
+    2. ``MLSPACE_ENV_FILE`` — an explicitly trusted file
+
+    Never read a checkout dotenv automatically: it could redirect saved credentials.
+
+    Real environment variables still beat every file; that is pydantic's own order.
+    """
+    files = [user_config_file()]
+    named = os.environ.get(ENV_FILE_VAR, "").strip()
+    if named:
+        files.append(Path(named))
+    return files
+
+
+def read_dotenv_file(path: Path) -> dict[str, str | None]:
+    """Parse a dotenv file, preserving literals in files written by current init."""
+    literal = False
+    if path.is_file():
+        literal = LITERAL_DOTENV_MARKER in path.read_text(encoding="utf-8").splitlines()
+    return dict(dotenv_values(path, interpolate=not literal))
+
+
+class ConnectedWorkspace(BaseModel):
+    """One workspace explicitly selected during ``mlspace-plugin setup``."""
+
+    model_config = ConfigDict(hide_input_in_errors=True)
+
+    id: str
+    name: str
+    project_name: str
+    api_key: SecretStr | None = None
+
+    @field_validator("id")
+    @classmethod
+    def nonblank_id(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Workspace id must not be blank")
+        return value
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="MLSPACE_", env_file=None, env_file_encoding="utf-8", extra="ignore",
+        hide_input_in_errors=True,
+    )
+
+    # credentials
+    client_id: str = ""
+    client_secret: SecretStr = SecretStr("")
+    api_key: SecretStr = SecretStr("")
+    workspace_id: str = ""
+    workspaces: list[ConnectedWorkspace] = Field(default_factory=list)
+    # optional: pin the workspace's k8s namespace; empty => resolved from workspace_id
+    namespace: str = ""
+    # where the credentials file was read from; set via MLSPACE_ENV_FILE. Kept on the
+    # instance so a missing-credential error can name the exact file to create.
+    env_file: str = ""
+
+    # endpoint / behaviour
+    ca_file: str = ""
+    base_url: str = DEFAULT_BASE_URL
+    # Write actions are available by default; the server is a working tool, not a
+    # viewer. What still stands between an agent and an irreversible change is the
+    # `confirm=true` gate on the 16 destructive actions, the jobs-delete existence
+    # precheck, and the preflight refusals — see registry.py.
+    readonly: bool = False
+    # dry-run: write/side-effecting actions are fully validated (body lint, path
+    # resolve, confirm gate) but NOT sent — the tool returns a preview of the request
+    # that WOULD be issued. Lets an LLM safely assemble & check a write before it runs.
+    dry_run: bool = False
+    transport: str = "streamable-http"  # streamable-http | stdio
+    host: str = "127.0.0.1"
+    port: int = 8000
+    timeout: float = 60.0
+    enabled_domains: str = ""  # comma-separated; empty = all
+
+    # response shaping
+    list_default_limit: int = Field(default=50, ge=1)
+    list_max_limit: int = Field(default=200, ge=1)
+    log_tail_lines: int = Field(default=200, ge=1)
+
+    @property
+    def enabled_domain_set(self) -> set[str] | None:
+        names = {d.strip() for d in self.enabled_domains.split(",") if d.strip()}
+        return names or None
+
+    def require_credentials(self) -> None:
+        """Raise if any required credential is unset (call before serving requests).
+
+        When a credentials file was named (the plugin bundle always names one), the
+        error quotes its absolute path and a ready-to-paste body: the caller running
+        us inside a plugin cannot otherwise know where that directory lives, and
+        "set these four variables" is useless advice when the client sanitizes the
+        environment it hands us.
+        """
+        required = [
+            ("CLIENT_ID", self.client_id),
+            ("CLIENT_SECRET", self.client_secret.get_secret_value()),
+        ]
+        if not self.workspaces:
+            required.append(("WORKSPACE_ID", self.workspace_id))
+        missing = ["MLSPACE_" + name for name, value in required if not value]
+        if not missing:
+            return
+
+        target = Path(self.env_file) if self.env_file else user_config_file()
+        state = "is empty or lacks them" if target.is_file() else "does not exist yet"
+        looked_in = ", ".join(str(p) for p in credential_files())
+        raise RuntimeError(
+            "\n".join(
+                [
+                    "Missing required credentials: " + ", ".join(missing) + ".",
+                    f"Looked in: {looked_in}, and the environment.",
+                    "",
+                    f"Fix it: `mlspace-plugin setup` writes {target} for you.",
+                    f"Or create it by hand ({target} {state}):",
+                    *(f"  MLSPACE_{name}=..." for name in CREDENTIALS),
+                ]
+            )
+        )
+
+    def validate_bind(self) -> None:
+        """Fail closed: v1 has no server-side auth, so refuse a non-loopback HTTP bind."""
+        host = self.host.strip("[]").lower()  # accept bracketed/again-cased IPv6 loopback
+        if self.transport != "stdio" and host not in LOOPBACK_HOSTS:
+            raise RuntimeError(
+                f"Refusing to bind streamable-HTTP to non-loopback host {self.host!r}: "
+                "this server has no built-in authentication and would expose shared "
+                "write credentials to the network. Bind 127.0.0.1 (default) and put it "
+                "behind an authenticated proxy for remote access."
+            )
+
+
+def load_settings() -> Settings:
+    """Build ``Settings`` from the credential search order in ``credential_files``.
+
+    ``env_file`` is fixed on the model at class-definition time, so the chain has to
+    be supplied per-instantiation. Real environment variables still win over every
+    file — pydantic's own order — so an ambient ``MLSPACE_*`` setup is untouched.
+    """
+    named = os.environ.get(ENV_FILE_VAR, "").strip()
+    if named and os.path.isdir(named):
+        raise RuntimeError(
+            f"{ENV_FILE_VAR}={named!r} is a directory; it must name the credentials "
+            "FILE itself, e.g. .../.env"
+        )
+    files = credential_files()
+    sources: list[dict[str, str | None]] = []
+    for path in files:
+        values = read_dotenv_file(path) if path.is_file() else {}
+        sources.append({key.upper(): value for key, value in values.items()})
+    sources.append({key.upper(): value for key, value in os.environ.items()})
+
+    selector_source = -1
+    selector_kind = ""
+    selected_catalogue: list[ConnectedWorkspace] = []
+    for index in range(len(sources) - 1, -1, -1):
+        source = sources[index]
+        if "MLSPACE_WORKSPACES" in source:
+            parsed = json.loads(str(source.get("MLSPACE_WORKSPACES") or ""))
+            selected_catalogue = [ConnectedWorkspace.model_validate(item) for item in parsed]
+            selector_source = index
+            selector_kind = "catalogue" if selected_catalogue else "legacy"
+            break
+        if str(source.get("MLSPACE_WORKSPACE_ID") or "").strip():
+            selector_source = index
+            selector_kind = "legacy"
+            break
+
+    merged: dict[str, Any] = {}
+    for source in sources:
+        for key, value in source.items():
+            if not key.startswith("MLSPACE_") or value is None:
+                continue
+            field_name = key.removeprefix("MLSPACE_").lower()
+            if field_name in Settings.model_fields and field_name != "workspaces":
+                merged[field_name] = value
+    merged["workspaces"] = selected_catalogue if selector_kind == "catalogue" else []
+    settings = Settings(_env_file=None, **merged)  # type: ignore[call-arg]
+
+    # Workspace selection is one context rather than independent fields. Track the
+    # provenance of selectors and workspace-bound scalar values before normalizing.
+    api_key_source = -1
+    api_key_workspace_id = ""
+    api_key_value = ""
+    namespace_source = -1
+    namespace_workspace_id = ""
+    namespace_value = ""
+    legacy_workspace_id = ""
+    for index, source in enumerate(sources):
+        source_workspace_id = str(source.get("MLSPACE_WORKSPACE_ID") or "").strip()
+        if source_workspace_id:
+            legacy_workspace_id = source_workspace_id
+        if "MLSPACE_API_KEY" in source:
+            api_key_source = index
+            api_key_workspace_id = legacy_workspace_id
+            api_key_value = str(source.get("MLSPACE_API_KEY") or "")
+        if "MLSPACE_NAMESPACE" in source:
+            namespace_source = index
+            namespace_workspace_id = legacy_workspace_id
+            namespace_value = str(source.get("MLSPACE_NAMESPACE") or "")
+
+    if selector_kind == "legacy":
+        settings.workspaces = []
+        selected_id = settings.workspace_id
+
+        effective_key_source = api_key_source if api_key_workspace_id == selected_id else -1
+        effective_key = api_key_value if effective_key_source >= 0 else ""
+        for index in range(selector_source - 1, -1, -1):
+            raw_catalogue = sources[index].get("MLSPACE_WORKSPACES")
+            if raw_catalogue is None:
+                continue
+            try:
+                parsed = json.loads(str(raw_catalogue))
+                catalogue = [ConnectedWorkspace.model_validate(item) for item in parsed]
+            except (TypeError, ValueError):
+                continue
+            match = next((item for item in catalogue if item.id == selected_id), None)
+            if index > effective_key_source:
+                effective_key_source = index
+                effective_key = (
+                    match.api_key.get_secret_value() if match is not None and match.api_key else ""
+                )
+            break
+        settings.api_key = SecretStr(effective_key)
+
+        if namespace_workspace_id != selected_id:
+            settings.namespace = ""
+        elif namespace_source >= 0:
+            settings.namespace = namespace_value
+    elif selector_kind == "catalogue" and len(settings.workspaces) == 1:
+        workspace = settings.workspaces[0]
+        if api_key_source > selector_source and api_key_workspace_id == workspace.id:
+            workspace.api_key = SecretStr(api_key_value) if api_key_value else None
+    return settings