synapse-sdk 1.0.0a11__py3-none-any.whl → 2026.1.1b2__py3-none-any.whl

synapse_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""
+Export / Import Guidelines
+--------------------------
+
+1. Do NOT import the top-level package directly.
+   - All imports must start from at least two levels below the root package.
+     (e.g., `project.module.submodule` is allowed,
+            `project` 또는 `project.module` 단일 import는 금지)
+
+2. Wildcard import (`from x import *`) is strictly prohibited.
+   - 모든 외부 노출(export)은 명시적인 이름 기반으로 관리해야 한다.
+   - `__all__` 리스트를 통해 공개할 API를 명확히 정의할 것.
+
+3. Public API 를 구성할 때:
+   - 하위 모듈에서 export할 항목만 `__all__`에 선언한다.
+   - 내부 구현용 함수/클래스는 `_` prefix 를 사용하거나 `__all__`에 포함하지 않는다.
+
+4. 모듈 간 의존성은 최단 경로만 허용한다.
+   - 불필요한 상위/평행 패키지 import 경로는 금지하여 순환 의존성(circular dependency)을 방지한다.
+"""
+
+from synapse_sdk.shared import worker_process_setup_hook
+
+__all__ = ['worker_process_setup_hook']

synapse_sdk/cli/__init__.py

@@ -1,11 +1,12 @@
-import click
+"""Synapse SDK CLI.
 
-from synapse_sdk.cli.create_plugin import create_plugin
+Usage:
+    synapse --help
+    synapse run <plugin> <action> [--params JSON]
+    synapse config <path> [--format yaml|json]
+    synapse version
+"""
 
+from synapse_sdk.cli.main import cli
 
-@click.group()
-def cli():
-    pass
-
-
-cli.add_command(create_plugin)
+__all__ = ['cli']

synapse_sdk/cli/agent/__init__.py

@@ -0,0 +1,25 @@
+"""Agent CLI commands."""
+
+from synapse_sdk.cli.agent.config import (
+    AgentConfig,
+    clear_agent_config,
+    get_agent_config,
+    set_agent_config,
+)
+from synapse_sdk.cli.agent.select import (
+    check_agent_connection,
+    fetch_agents,
+    select_agent_interactive,
+)
+
+__all__ = [
+    # Config
+    'AgentConfig',
+    'get_agent_config',
+    'set_agent_config',
+    'clear_agent_config',
+    # Selection
+    'fetch_agents',
+    'select_agent_interactive',
+    'check_agent_connection',
+]

synapse_sdk/cli/agent/config.py

@@ -0,0 +1,104 @@
+"""Agent configuration management."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+# Config file path
+CONFIG_DIR = Path.home() / '.synapse'
+CONFIG_FILE = CONFIG_DIR / 'config.json'
+
+
+@dataclass
+class AgentConfig:
+    """Agent configuration."""
+
+    id: int
+    name: str | None = None
+    url: str | None = None
+    token: str | None = None
+
+
+def _ensure_config_dir() -> None:
+    """Ensure the config directory exists."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load_config() -> dict:
+    """Load configuration from file."""
+    _ensure_config_dir()
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def _save_config(config: dict) -> None:
+    """Save configuration to file."""
+    _ensure_config_dir()
+    CONFIG_FILE.write_text(json.dumps(config, indent=2))
+    CONFIG_FILE.chmod(0o600)
+
+
+def get_agent_config() -> AgentConfig | None:
+    """Get current agent configuration.
+
+    Returns:
+        AgentConfig if configured, None otherwise.
+    """
+    config = _load_config()
+    agent = config.get('agent')
+    if not agent or 'id' not in agent:
+        return None
+    return AgentConfig(
+        id=agent['id'],
+        name=agent.get('name'),
+        url=agent.get('url'),
+        token=agent.get('token'),
+    )
+
+
+def set_agent_config(
+    agent_id: int,
+    *,
+    name: str | None = None,
+    url: str | None = None,
+    token: str | None = None,
+) -> None:
+    """Set agent configuration.
+
+    Args:
+        agent_id: Agent ID.
+        name: Agent name.
+        url: Agent URL.
+        token: Agent authentication token.
+    """
+    config = _load_config()
+    config['agent'] = {'id': agent_id}
+    if name:
+        config['agent']['name'] = name
+    if url:
+        config['agent']['url'] = url
+    if token:
+        config['agent']['token'] = token
+    _save_config(config)
+
+
+def clear_agent_config() -> None:
+    """Clear agent configuration."""
+    config = _load_config()
+    if 'agent' in config:
+        del config['agent']
+    _save_config(config)
+
+
+__all__ = [
+    'AgentConfig',
+    'get_agent_config',
+    'set_agent_config',
+    'clear_agent_config',
+]

synapse_sdk/cli/agent/select.py

@@ -0,0 +1,197 @@
+"""Agent selection and connection utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import questionary
+import requests
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from synapse_sdk.cli.agent.config import AgentConfig, set_agent_config
+from synapse_sdk.cli.auth import AuthConfig
+from synapse_sdk.clients.backend import Agent, BackendClient
+
+
+@dataclass
+class ConnectionResult:
+    """Result of connection test."""
+
+    success: bool
+    message: str
+
+
+def fetch_agents(auth: AuthConfig) -> list[Agent]:
+    """Fetch available agents from the backend.
+
+    Args:
+        auth: Authentication configuration.
+
+    Returns:
+        List of Agent objects.
+    """
+    client = BackendClient(auth.host, access_token=auth.access_token)
+    return client.list_agents()
+
+
+def check_agent_connection(url: str, token: str, *, timeout: int = 5) -> ConnectionResult:
+    """Test agent connection.
+
+    Args:
+        url: Agent URL.
+        token: Agent authentication token.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        ConnectionResult with success status and message.
+    """
+    if not url or not token:
+        return ConnectionResult(success=True, message='Agent configured (no URL/token to test)')
+
+    try:
+        response = requests.get(
+            f'{url.rstrip("/")}/health/',
+            headers={'Authorization': token},
+            timeout=timeout,
+        )
+
+        if response.status_code == 200:
+            return ConnectionResult(success=True, message='Connection successful')
+        elif response.status_code == 401:
+            return ConnectionResult(success=False, message='Invalid agent token (401)')
+        elif response.status_code == 403:
+            return ConnectionResult(success=False, message='Access forbidden (403)')
+        else:
+            return ConnectionResult(success=False, message=f'HTTP {response.status_code}')
+
+    except requests.exceptions.Timeout:
+        return ConnectionResult(success=False, message=f'Connection timeout (>{timeout}s)')
+    except requests.exceptions.ConnectionError:
+        return ConnectionResult(success=False, message='Connection failed')
+    except Exception as e:
+        return ConnectionResult(success=False, message=f'Error: {e}')
+
+
+def display_agents_table(agents: list[Agent], console: Console) -> None:
+    """Display agents in a table format.
+
+    Args:
+        agents: List of agents to display.
+        console: Rich console for output.
+    """
+    table = Table(title='Available Agents', show_header=True, header_style='bold')
+    table.add_column('ID', style='dim')
+    table.add_column('Name')
+    table.add_column('Status')
+    table.add_column('URL', style='dim')
+
+    for agent in agents:
+        status = agent.status or 'unknown'
+        status_style = 'green' if agent.is_connected else 'red'
+        table.add_row(
+            str(agent.id),
+            agent.name,
+            f'[{status_style}]{status}[/{status_style}]',
+            agent.url or '-',
+        )
+
+    console.print(table)
+
+
+def select_agent_interactive(
+    auth: AuthConfig,
+    console: Console,
+) -> AgentConfig | None:
+    """Interactively select an agent from the backend.
+
+    Args:
+        auth: Authentication configuration.
+        console: Rich console for output.
+
+    Returns:
+        Selected AgentConfig if successful, None if cancelled.
+    """
+    console.print('[dim]Fetching available agents...[/dim]')
+
+    try:
+        agents = fetch_agents(auth)
+    except Exception as e:
+        console.print(f'[red]Error fetching agents:[/red] {e}')
+        return None
+
+    if not agents:
+        console.print('[yellow]No agents found in current workspace.[/yellow]')
+        return None
+
+    # Create ID lookup map
+    agents_by_id = {agent.id: agent for agent in agents}
+
+    # Display the nice Rich table
+    console.print()
+    display_agents_table(agents, console)
+    console.print()
+
+    # Prompt for agent ID
+    agent_id_str = questionary.text(
+        'Enter agent ID (leave empty to cancel):',
+    ).ask()
+
+    if not agent_id_str:
+        return None
+
+    try:
+        agent_id = int(agent_id_str)
+    except ValueError:
+        console.print(f'[red]Invalid ID:[/red] {agent_id_str}')
+        return None
+
+    selected = agents_by_id.get(agent_id)
+    if not selected:
+        console.print(f'[red]Agent not found:[/red] {agent_id}')
+        return None
+
+    # Save configuration
+    set_agent_config(
+        selected.id,
+        name=selected.name,
+        url=selected.url,
+        token=selected.token,
+    )
+
+    # Display success
+    console.print()
+    console.print(
+        Panel(
+            f'[bold]{selected.name}[/bold]\n\nID: {selected.id}\nURL: {selected.url or "Not set"}',
+            title='Agent Selected',
+            border_style='green',
+        )
+    )
+
+    # Test connection if URL and token are available
+    if selected.url and selected.token:
+        console.print()
+        console.print('[dim]Testing connection...[/dim]')
+        result = check_agent_connection(selected.url, selected.token)
+        if result.success:
+            console.print(f'[green]{result.message}[/green]')
+        else:
+            console.print(f'[red]{result.message}[/red]')
+
+    return AgentConfig(
+        id=selected.id,
+        name=selected.name,
+        url=selected.url,
+        token=selected.token,
+    )
+
+
+__all__ = [
+    'ConnectionResult',
+    'fetch_agents',
+    'check_agent_connection',
+    'display_agents_table',
+    'select_agent_interactive',
+]

synapse_sdk/cli/auth.py

@@ -0,0 +1,104 @@
+"""CLI authentication utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import questionary
+import typer
+from rich.console import Console
+
+from synapse_sdk.utils.auth import (
+    CONFIG_FILE,
+    DEFAULT_HOST,
+    ENV_SYNAPSE_ACCESS_TOKEN,
+    ENV_SYNAPSE_HOST,
+    load_credentials,
+)
+
+
+@dataclass
+class AuthConfig:
+    """Authentication configuration."""
+
+    host: str
+    access_token: str
+
+
+def load_credentials_file() -> dict[str, str]:
+    """Load credentials from ~/.synapse/config.json file.
+
+    Returns:
+        Dict with SYNAPSE_HOST and SYNAPSE_ACCESS_TOKEN if found.
+    """
+    host, token = load_credentials()
+    credentials: dict[str, str] = {}
+    if host:
+        credentials[ENV_SYNAPSE_HOST] = host
+    if token:
+        credentials[ENV_SYNAPSE_ACCESS_TOKEN] = token
+    return credentials
+
+
+def get_auth_config(
+    *,
+    host: str | None = None,
+    token: str | None = None,
+    console: Console | None = None,
+    interactive: bool = True,
+) -> AuthConfig:
+    """Get authentication configuration.
+
+    Priority order:
+    1. CLI options (--host, --token)
+    2. Environment variables (SYNAPSE_HOST, SYNAPSE_ACCESS_TOKEN)
+    3. Config file (~/.synapse/config.json)
+    4. Interactive prompt (if interactive=True)
+
+    Args:
+        host: Host override from CLI.
+        token: Token override from CLI.
+        console: Rich console for output.
+        interactive: Whether to prompt for missing values.
+
+    Returns:
+        AuthConfig with host and access_token.
+
+    Raises:
+        typer.Exit: If authentication cannot be resolved.
+    """
+    # Load from env/credentials file
+    loaded_host, loaded_token = load_credentials()
+
+    # Resolve host (CLI > loaded > default)
+    resolved_host = host or loaded_host or DEFAULT_HOST
+
+    # Resolve token (CLI > loaded)
+    resolved_token = token or loaded_token
+
+    if not resolved_token and interactive:
+        resolved_token = questionary.text(
+            'Enter your Synapse access token:',
+            validate=lambda x: len(x) > 0 or 'Token cannot be empty',
+        ).ask()
+
+        if not resolved_token:
+            raise typer.Exit(1)
+
+    if not resolved_token:
+        raise typer.BadParameter(
+            f'Not authenticated. Run `synapse login` or set {ENV_SYNAPSE_ACCESS_TOKEN} environment variable.'
+        )
+
+    return AuthConfig(host=resolved_host, access_token=resolved_token)
+
+
+__all__ = [
+    'AuthConfig',
+    'get_auth_config',
+    'load_credentials_file',
+    'ENV_SYNAPSE_HOST',
+    'ENV_SYNAPSE_ACCESS_TOKEN',
+    'DEFAULT_HOST',
+    'CONFIG_FILE',
+]