smanager 0.1.0__tar.gz

smanager-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: smanager
+Version: 0.1.0
+Requires-Python: >=3.9
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: click>=8.0

smanager-0.1.0/README.md

@@ -0,0 +1,10 @@
+# SManager
+> A simple server manager for self-hosted services, with VPN integration and support for both local and Docker-based services.
+
+## Features
+- Manage local services and Docker containers with a unified interface.
+- Integrate with Tailscale VPN for secure remote access.
+- Monitor service status and logs in real-time.
+- Easy configuration using YAML files.
+- Extensible architecture for adding new service types and VPN providers.
+

smanager-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smanager"
+dynamic = ["version"]
+requires-python = ">=3.9"
+dependencies = [
+    "PyYAML>=6.0",
+    "click>=8.0",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "smanager.__version__"}
+
+[project.scripts]
+smanager = "smanager.cli.main:cli"

smanager-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smanager-0.1.0/smanager/__init__.py

@@ -0,0 +1,13 @@
+__version__ = "0.1.0"
+
+from .global_manager import GlobalManager
+from .datatypes import GlobalConfig, Service, ServiceStatus, MultiStatus
+
+__all__ = [
+    "__version__",
+    "GlobalManager",
+    "GlobalConfig",
+    "Service",
+    "ServiceStatus",
+    "MultiStatus",
+]

smanager-0.1.0/smanager/cli/commands/__init__.py

@@ -0,0 +1,10 @@
+ACTIONS = ("start", "stop", "restart", "enable", "disable")
+
+from .service import service_cmd
+from .group import group_cmd
+from .dependency import dependency_cmd
+from .all import all_cmd
+from .status import status_cmd
+from .config import config_cmd
+
+__all__ = ["ACTIONS", "service_cmd", "group_cmd", "dependency_cmd", "all_cmd", "status_cmd", "config_cmd"]

smanager-0.1.0/smanager/cli/commands/all.py

@@ -0,0 +1,35 @@
+import click
+
+from . import ACTIONS
+from ..config import get_manager
+
+
+@click.command("all")
+@click.argument("action", type=click.Choice(ACTIONS, case_sensitive=False))
+@click.option(
+    "--yes",
+    is_flag=True,
+    default=False,
+    help="Confirm the operation on all services.",
+)
+@click.pass_context
+def all_cmd(ctx: click.Context, action: str, yes: bool) -> None:
+    """Perform ACTION on ALL managed services.
+
+    \b
+    Actions: start, stop, restart, enable, disable
+
+    Requires --yes to prevent accidental execution.
+    """
+    if not yes:
+        raise click.UsageError(
+            f"This will run '{action}' on ALL services. Pass --yes to confirm."
+        )
+    manager = get_manager(ctx)
+    try:
+        manager.manage_all(action)
+        click.echo(f"[OK] '{action}' on all services.")
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    except RuntimeError as e:
+        raise click.ClickException(str(e))

smanager-0.1.0/smanager/cli/commands/config.py

@@ -0,0 +1,61 @@
+import os
+
+import click
+
+from ..config import DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_PATH, resolve_config_path
+
+_TEMPLATE = """\
+global:
+  # Absolute path to the directory where service sd_info.json files live.
+  services_dir: "/path/to/your/services"
+
+  # VPN provider to use. Must match a registered provider (e.g. "tailscale").
+  vpn_provider: "tailscale"
+"""
+
+
+@click.group("config")
+def config_cmd() -> None:
+    """Manage the smanager configuration file."""
+
+
+@config_cmd.command("init")
+@click.option("--force", is_flag=True, help="Overwrite existing config.")
+def init_cmd(force: bool) -> None:
+    """Create a template config at the default location.
+
+    \b
+    Default: ~/.config/smanager/smanager.yaml
+    """
+    if os.path.exists(DEFAULT_CONFIG_PATH) and not force:
+        raise click.ClickException(
+            f"Config already exists at {DEFAULT_CONFIG_PATH}. "
+            "Use --force to overwrite."
+        )
+    os.makedirs(DEFAULT_CONFIG_DIR, exist_ok=True)
+    with open(DEFAULT_CONFIG_PATH, "w") as f:
+        f.write(_TEMPLATE)
+    click.echo(f"Config created: {DEFAULT_CONFIG_PATH}")
+
+
+@config_cmd.command("edit")
+@click.pass_context
+def edit_cmd(ctx: click.Context) -> None:
+    """Open the config file in $EDITOR (falls back to nano).
+
+    \b
+    Resolves the config path in the same order as all other commands:
+      1. --config PATH
+      2. $SMANAGER_CONFIG
+      3. ~/.config/smanager/smanager.yaml
+      4. /etc/smanager/smanager.yaml
+      5. ./smanager.yaml
+    """
+    try:
+        path = resolve_config_path(ctx.obj.get("config_path"))
+    except click.ClickException:
+        raise click.ClickException(
+            "No config file found. Run 'smanager config init' first."
+        )
+    editor = os.environ.get("EDITOR", "nano")
+    click.edit(filename=path, editor=editor)

smanager-0.1.0/smanager/cli/commands/dependency.py

@@ -0,0 +1,24 @@
+import click
+
+from . import ACTIONS
+from ..config import get_manager
+
+
+@click.command()
+@click.argument("action", type=click.Choice(ACTIONS, case_sensitive=False))
+@click.argument("dependency_name")
+@click.pass_context
+def dependency_cmd(ctx: click.Context, action: str, dependency_name: str) -> None:
+    """Perform ACTION on all services that depend on DEPENDENCY_NAME.
+
+    \b
+    Actions: start, stop, restart, enable, disable
+    """
+    manager = get_manager(ctx)
+    try:
+        manager.manage_by_dependency(dependency_name, action)
+        click.echo(f"[OK] '{action}' on services depending on '{dependency_name}'.")
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    except RuntimeError as e:
+        raise click.ClickException(str(e))

smanager-0.1.0/smanager/cli/commands/group.py

@@ -0,0 +1,24 @@
+import click
+
+from . import ACTIONS
+from ..config import get_manager
+
+
+@click.command()
+@click.argument("action", type=click.Choice(ACTIONS, case_sensitive=False))
+@click.argument("group_name")
+@click.pass_context
+def group_cmd(ctx: click.Context, action: str, group_name: str) -> None:
+    """Perform ACTION on all services in GROUP_NAME.
+
+    \b
+    Actions: start, stop, restart, enable, disable
+    """
+    manager = get_manager(ctx)
+    try:
+        manager.manage_group(group_name, action)
+        click.echo(f"[OK] '{action}' on group '{group_name}'.")
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    except RuntimeError as e:
+        raise click.ClickException(str(e))

smanager-0.1.0/smanager/cli/commands/service.py

@@ -0,0 +1,24 @@
+import click
+
+from . import ACTIONS
+from ..config import get_manager
+
+
+@click.command()
+@click.argument("action", type=click.Choice(ACTIONS, case_sensitive=False))
+@click.argument("service_id")
+@click.pass_context
+def service_cmd(ctx: click.Context, action: str, service_id: str) -> None:
+    """Perform ACTION on a single service.
+
+    \b
+    Actions: start, stop, restart, enable, disable
+    """
+    manager = get_manager(ctx)
+    try:
+        manager.manage_service(service_id, action)
+        click.echo(f"[OK] '{action}' on service '{service_id}'.")
+    except ValueError as e:
+        raise click.ClickException(str(e))
+    except RuntimeError as e:
+        raise click.ClickException(str(e))

smanager-0.1.0/smanager/cli/commands/status.py

@@ -0,0 +1,85 @@
+import dataclasses
+import json as json_module
+
+import click
+
+from ..config import get_manager
+from ...datatypes import MultiStatus, ServiceStatus
+
+
+def _print_service_status(status: ServiceStatus) -> None:
+    click.echo(f"Service: {status.id}  [{status.type}]")
+    for s in status.statuses:
+        marker = "●" if s.status in ("running", "active") else "○"
+        click.echo(f"  {marker} {s.name}: {s.status}")
+
+
+def _print_multi_status(multi: MultiStatus) -> None:
+    for i, svc in enumerate(multi.services):
+        if i > 0:
+            click.echo("")
+        _print_service_status(svc)
+
+
+@click.command()
+@click.option("--service", "service_id", default=None, metavar="ID",
+              help="Status of a single service.")
+@click.option("--group", "group_name", default=None, metavar="NAME",
+              help="Status of all services in a group.")
+@click.option("--dependency", "dependency_name", default=None, metavar="NAME",
+              help="Status of services by dependency.")
+@click.option("--all", "all_services", is_flag=True, default=False,
+              help="Status of all services.")
+@click.option("--json", "as_json", is_flag=True, default=False,
+              help="Output as JSON.")
+@click.pass_context
+def status_cmd(
+    ctx: click.Context,
+    service_id: str | None,
+    group_name: str | None,
+    dependency_name: str | None,
+    all_services: bool,
+    as_json: bool,
+) -> None:
+    """Show the status of services.
+
+    \b
+    Provide exactly one scope:
+      --service ID        single service
+      --group NAME        all services in a group
+      --dependency NAME   all services by dependency
+      --all               every managed service
+    """
+    scopes = [x for x in [service_id, group_name, dependency_name] if x] + (
+        [True] if all_services else []
+    )
+    if len(scopes) == 0:
+        raise click.UsageError(
+            "Provide one of: --service, --group, --dependency, --all"
+        )
+    if len(scopes) > 1:
+        raise click.UsageError(
+            "Only one of --service, --group, --dependency, --all can be used at a time."
+        )
+
+    manager = get_manager(ctx)
+    try:
+        if service_id:
+            result = manager.get_status(service_id)
+            if as_json:
+                click.echo(json_module.dumps(dataclasses.asdict(result), indent=2))
+            else:
+                _print_service_status(result)
+        else:
+            if group_name:
+                result = manager.get_group_status(group_name)
+            elif dependency_name:
+                result = manager.get_dependency_status(dependency_name)
+            else:
+                result = manager.get_all_status()
+            if as_json:
+                click.echo(json_module.dumps(dataclasses.asdict(result), indent=2))
+            else:
+                _print_multi_status(result)
+    except ValueError as e:
+        raise click.ClickException(str(e))

smanager-0.1.0/smanager/cli/config.py

@@ -0,0 +1,75 @@
+"""
+Config loading and GlobalManager initialisation for the CLI.
+"""
+import os
+
+import click
+
+from ..datatypes import GlobalConfig
+from ..global_manager import GlobalManager
+from ..vpn import get_vpn
+
+
+# ---------------------------------------------------------------------------
+# Default paths (XDG-compliant)
+# ---------------------------------------------------------------------------
+_XDG_CONFIG_HOME = os.environ.get(
+    "XDG_CONFIG_HOME", os.path.expanduser("~/.config")
+)
+DEFAULT_CONFIG_DIR = os.path.join(_XDG_CONFIG_HOME, "smanager")
+DEFAULT_CONFIG_PATH = os.path.join(DEFAULT_CONFIG_DIR, "smanager.yaml")
+SYSTEM_CONFIG_PATH = "/etc/smanager/smanager.yaml"
+
+# Ordered list of locations tried when no explicit path is given.
+_SEARCH_PATHS = [
+    DEFAULT_CONFIG_PATH,
+    SYSTEM_CONFIG_PATH,
+    "smanager.yaml",  # legacy local fallback
+]
+
+
+def resolve_config_path(config_path: str | None) -> str:
+    """Return the resolved config file path or raise ClickException."""
+    if config_path is not None:
+        return config_path
+    env = os.environ.get("SMANAGER_CONFIG")
+    if env:
+        return env
+    for path in _SEARCH_PATHS:
+        if os.path.isfile(path):
+            return path
+    raise click.ClickException(
+        f"No config file found. Run 'smanager config init' to create one at "
+        f"{DEFAULT_CONFIG_PATH}."
+    )
+
+
+def build_manager(config_path: str | None) -> GlobalManager:
+    """Resolve a config file and return an initialised GlobalManager."""
+    path = resolve_config_path(config_path)
+    with open(path) as f:
+        try:
+            config = GlobalConfig.from_yaml(f.read())
+        except ValueError as e:
+            raise click.ClickException(str(e))
+    if not config.services_dir:
+        raise click.ClickException("'services_dir' is not set in the config file.")
+    if not os.path.isdir(config.services_dir):
+        raise click.ClickException(
+            f"services_dir does not exist: {config.services_dir}"
+        )
+    try:
+        vpn_cls = get_vpn(config.vpn_provider)
+        vpn = vpn_cls()
+    except ValueError as e:
+        raise click.ClickException(
+            f"Unknown VPN provider '{config.vpn_provider}': {e}"
+        )
+    return GlobalManager(config.services_dir, config, vpn)
+
+
+def get_manager(ctx: click.Context) -> GlobalManager:
+    """Return the GlobalManager stored in *ctx*, building it lazily on first call."""
+    if ctx.obj.get("_manager") is None:
+        ctx.obj["_manager"] = build_manager(ctx.obj.get("config_path"))
+    return ctx.obj["_manager"]

smanager-0.1.0/smanager/cli/main.py

@@ -0,0 +1,30 @@
+import click
+
+from .commands import all_cmd, dependency_cmd, group_cmd, service_cmd, status_cmd
+from .commands import all_cmd, config_cmd, dependency_cmd, group_cmd, service_cmd, status_cmd
+
+
+@click.group()
+@click.option(
+    "--config",
+    "config_path",
+    envvar="SMANAGER_CONFIG",
+    default=None,
+    metavar="PATH",
+    help="Path to config file (or set SMANAGER_CONFIG). Default: ./smanager.yaml",
+)
+@click.version_option(package_name="smanager")
+@click.pass_context
+def cli(ctx: click.Context, config_path: str | None) -> None:
+    """SManager — manage self-hosted services and Docker containers."""
+    ctx.ensure_object(dict)
+    ctx.obj["config_path"] = config_path
+    ctx.obj["_manager"] = None
+
+
+cli.add_command(service_cmd, "service")
+cli.add_command(group_cmd, "group")
+cli.add_command(dependency_cmd, "dependency")
+cli.add_command(all_cmd, "all")
+cli.add_command(status_cmd, "status")
+cli.add_command(config_cmd, "config")

smanager-0.1.0/smanager/crawler/__init__.py

@@ -0,0 +1,5 @@
+from .sd_finder import ServiceDiscoverer
+
+__all__ = [
+    "ServiceDiscoverer"
+]

smanager-0.1.0/smanager/crawler/sd_finder.py

@@ -0,0 +1,32 @@
+"""
+Finds Service Discovery files in a given directory and parses them into Service objects.
+"""
+
+import os
+from ..datatypes import ServiceMetadata, Service
+
+class ServiceDiscoverer:
+    def __init__(self, directory: str, searched_filename: str = "sd_info.json"):
+        self.directory = directory
+        self.searched_filename = searched_filename
+
+    def discover_services(self) -> list[Service]:
+        """Walks through the directory to find SDConfig files, returns a list 
+        of Service objects.
+        """
+        services = []
+        for root, _, files in os.walk(self.directory):
+            if self.searched_filename in files:
+                sd_abspath = os.path.join(root, self.searched_filename)
+                with open(sd_abspath, 'r') as f:
+                    try:
+                        metadata = ServiceMetadata.from_json(f.read())
+                        service = Service(
+                            metadata=metadata, 
+                            service_abspath=root,
+                            metadata_filename=self.searched_filename
+                            )
+                        services.append(service)
+                    except Exception as e:
+                        print(f"Error parsing {sd_abspath}: {e}")
+        return services

smanager-0.1.0/smanager/datatypes/__init__.py

@@ -0,0 +1,19 @@
+from .sd_info_v2 import (
+    ServiceMetadata, RuntimeSection, PortSection, 
+    DockerSection, LocalSection, Service
+)
+from .config import GlobalConfig
+from .service_status import ServiceStatus, SingleStatus, MultiStatus
+
+__all__ = [
+    "ServiceMetadata",
+    "RuntimeSection",
+    "PortSection",
+    "DockerSection",
+    "LocalSection",
+    "GlobalConfig",
+    "Service",
+    "ServiceStatus",
+    "SingleStatus",
+    "MultiStatus"
+]

smanager-0.1.0/smanager/datatypes/config.py

@@ -0,0 +1,20 @@
+import yaml
+from dataclasses import dataclass, field
+
+@dataclass
+class GlobalConfig:
+    services_dir: str
+    vpn_provider: str = field(default="tailscale")
+
+    @classmethod
+    def from_yaml(cls, yaml_str: str) -> 'GlobalConfig':
+        """Parses a YAML string into a GlobalConfig object."""
+        try:
+            data = yaml.safe_load(yaml_str)
+            global_data = data.get('global', {})
+            return cls(
+                services_dir=global_data.get('services_dir', ''),
+                vpn_provider=global_data.get('vpn_provider', 'tailscale'),
+            )
+        except yaml.YAMLError as e:
+            raise ValueError(f"Error parsing YAML: {e}")

smanager-0.1.0/smanager/datatypes/sd_info_v2.py

@@ -0,0 +1,134 @@
+"""
+This module defines the data structures for the SDConfig v2
+"""
+from dataclasses import dataclass
+from typing import Optional
+import json
+import os
+
+
+@dataclass
+class PortSection:
+    webui: int
+
+    # Dinamically loads dict keys as attributes
+    def __post_init__(self):
+        for key, value in self.__dict__.items():
+            setattr(self, key, value)
+
+        if not hasattr(self, 'webui'):
+            raise ValueError("PortSection must have a 'webui' key.")
+
+@dataclass
+class RuntimeSection:
+    type: str
+    ports: PortSection
+    sys_user: str
+    sys_group: str
+
+    def __post_init__(self):
+        if not self.type:
+            raise ValueError("RuntimeSection must have a 'type' field.")
+        if not self.ports:
+            raise ValueError("RuntimeSection must have a 'ports' field.")
+        if not self.sys_user:
+            raise ValueError("RuntimeSection must have a 'sys_user' field.")
+        if not self.sys_group:
+            raise ValueError("RuntimeSection must have a 'sys_group' field.")
+
+@dataclass
+class DockerSection:
+    containers: Optional[list] = None
+    compose_file: Optional[str] = None
+
+@dataclass
+class LocalSection:
+    installation_path: Optional[str] = None
+    app_path: Optional[str] = None
+    systemd_services: Optional[list] = None
+
+@dataclass
+class ServiceMetadata:
+    name: str
+    description: str
+    schema_version: int
+    id: str
+    active: bool
+    runtime: RuntimeSection
+    groups: Optional[list] = None
+    docker: Optional[DockerSection] = None
+    local: Optional[LocalSection] = None
+    depends_on: Optional[list] = None
+
+    def __post_init__(self):
+        # Validate required fields
+        if not self.name:
+            raise ValueError("SDConfig must have a 'name' field.")
+        if not self.description:
+            raise ValueError("SDConfig must have a 'description' field.")
+        if not self.schema_version:
+            raise ValueError("SDConfig must have a 'schema_version' field.")
+        if not self.id:
+            raise ValueError("SDConfig must have an 'id' field.")
+        if self.active is None:
+            raise ValueError("SDConfig must have an 'active' field.")
+        if not self.runtime:
+            raise ValueError("SDConfig must have a 'runtime' field.")
+        
+        # Validate at least one of docker or local is provided
+        if not self.docker and not self.local:
+            raise ValueError("SDConfig must have at least one of 'docker' or 'local' sections.")
+        
+    @classmethod
+    def from_dict(cls, data: dict) -> 'ServiceMetadata':
+        runtime_data = data.get('runtime')
+        if not runtime_data:
+            raise ValueError("SDConfig must have a 'runtime' section.")
+        
+        runtime = RuntimeSection(
+            type=runtime_data.get('type'),
+            ports=PortSection(**runtime_data.get('ports', {})),
+            sys_user=runtime_data.get('sys_user'),
+            sys_group=runtime_data.get('sys_group')
+        )
+
+        docker_data = data.get('docker')
+        docker = DockerSection(**docker_data) if docker_data else None
+
+        local_data = data.get('local')
+        local = LocalSection(**local_data) if local_data else None
+
+        return cls(
+            name=data.get('name'),
+            description=data.get('description'),
+            schema_version=data.get('schema_version'),
+            id=data.get('id'),
+            groups=data.get('groups'),
+            active=data.get('active'),
+            runtime=runtime,
+            docker=docker,
+            local=local,
+            depends_on=data.get('depends_on')
+        )
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> 'ServiceMetadata':
+        return cls.from_dict(json.loads(json_str))
+    
+    def write_to_json(self, file_path: str):
+        with open(file_path, 'w') as f:
+            json.dump(self.__dict__, f, default=lambda o: o.__dict__, indent=4)
+
+@dataclass
+class Service:
+    metadata: ServiceMetadata
+    service_abspath: str
+    metadata_filename: str
+
+    def __post_init__(self):
+        if not os.path.isabs(self.service_abspath):
+            raise ValueError("Service 'service_abspath' must be an absolute path.")
+        if not os.path.exists(self.service_abspath):
+            raise ValueError(f"Service 'service_abspath' does not exist: {self.service_abspath}")
+        if not self.metadata_filename:
+            raise ValueError("Service must have a 'metadata_filename' field.")

smanager-0.1.0/smanager/datatypes/service_status.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+@dataclass
+class SingleStatus:
+    name: str
+    status: str
+
+@dataclass
+class ServiceStatus:
+    id: str
+    type: str  # e.g. "docker", "local"
+    statuses: list[SingleStatus]
+
+@dataclass
+class MultiStatus:
+    services: list[ServiceStatus]

smanager-0.1.0/smanager/global_manager/__init__.py

@@ -0,0 +1,7 @@
+from .base_global_manager import BaseGlobalManager
+from .global_manager import GlobalManager
+
+__all__ = [
+    "BaseGlobalManager",
+    "GlobalManager",
+]