sing-box-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sing-box-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: cross-platform sing-box manager.
 Project-URL: Homepage, https://github.com/aittcuszz/sing-box-service
 Project-URL: Issues, https://github.com/atticuszz/sing-box-service/issues
@@ -69,31 +69,81 @@ Linux
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-### sing-box
-
-Windows
+### sing-box-cli
 
+Install
 ```powershell
+# windows
 uv tool install sing-box-cli
 ```
 
-Linux
-
 ```bash
+# linux
 uv tool install sing-box-cli
 sudo ln -sf $(which sing-box-cli) /usr/local/bin/
+sudo ln -sf $(which sbc) /usr/local/bin/
+```
+
+Install with specific sing-box version
+
+```bash
+uv tool install sing-box-cli --with sing-box-bin==x.y.z
 ```
 
+Upgrade
+```bash
+uv tool upgrade sing-box-cli
+```
+
+After upgrading on Windows, run the following in an administrator PowerShell:
+
+```powershell
+sbc service enable
+sbc service status
+```
+
+This refreshes the installed service paths and migrates existing NSSM installations
+to the native Go service host, keeping the same `sing-box-service` name and account.
+An existing running service is stopped and restarted when its executable paths change.
+If that update fails, the old service target is restored and the error is reported.
+
+The native host and core are copied into versioned directories under
+`%ProgramFiles%/sing-box-cli/sing-box-service`. The running service does not depend
+on uv's environment, so future uv upgrades do not overwrite its running executables.
+Configuration files stay in their existing location. Windows services run at boot;
+closing the terminal does not stop them. Linux continues to use the existing systemd service.
+
+No Go installation is required when installing a published wheel. Go is needed
+only to build a wheel from source; the required version is in `windows-service/go.mod`.
+Architecture support follows `sing-box-bin`: Windows distributes the amd64 core
+and service helper; Linux distributes amd64 and arm64 cores. No additional CPU
+architectures are introduced by the service helper.
+
+### Logs
+
+The service uses the user's sing-box configuration without changing its log level.
+Set `log.level` to `info` or `warn` in that configuration to reduce generated logs.
+`sbc logs --log-level debug` selects the logs to view; it cannot recover debug entries
+that the core did not generate. For diagnostics, explicitly change the core's log level
+and restart, then restore it when finished.
+
+The native Windows host writes only warnings/errors to the Windows Application event
+log (source `sing-box-service-native`). Core stdout/stderr is kept as a bounded diagnostic
+tail for failures, without an additional debug log file. To persist core logs, use
+sing-box's `log.output` configuration; streaming `sbc logs` continues to use the core API.
+Old versioned executables are retained for rollback. After disabling the service,
+its directory under Program Files may be removed manually; user configuration is separate.
+
 ## Run
 
 Windows in Admin powershell
 
 ```powershell
-sing-box-cli --help
+sbc --help
 ```
 
 Linux
 
 ```bash
-sudo sing-box-cli --help
+sudo sbc --help
 ```

sing_box_cli-0.1.2/README.md

@@ -0,0 +1,100 @@
+# Sing-Box CLI
+
+🎤 Cross-platform sing-box service manager.
+
+![help](assets/image.png)
+
+## Install
+
+### uv
+
+Windows
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### sing-box-cli
+
+Install
+```powershell
+# windows
+uv tool install sing-box-cli
+```
+
+```bash
+# linux
+uv tool install sing-box-cli
+sudo ln -sf $(which sing-box-cli) /usr/local/bin/
+sudo ln -sf $(which sbc) /usr/local/bin/
+```
+
+Install with specific sing-box version
+
+```bash
+uv tool install sing-box-cli --with sing-box-bin==x.y.z
+```
+
+Upgrade
+```bash
+uv tool upgrade sing-box-cli
+```
+
+After upgrading on Windows, run the following in an administrator PowerShell:
+
+```powershell
+sbc service enable
+sbc service status
+```
+
+This refreshes the installed service paths and migrates existing NSSM installations
+to the native Go service host, keeping the same `sing-box-service` name and account.
+An existing running service is stopped and restarted when its executable paths change.
+If that update fails, the old service target is restored and the error is reported.
+
+The native host and core are copied into versioned directories under
+`%ProgramFiles%/sing-box-cli/sing-box-service`. The running service does not depend
+on uv's environment, so future uv upgrades do not overwrite its running executables.
+Configuration files stay in their existing location. Windows services run at boot;
+closing the terminal does not stop them. Linux continues to use the existing systemd service.
+
+No Go installation is required when installing a published wheel. Go is needed
+only to build a wheel from source; the required version is in `windows-service/go.mod`.
+Architecture support follows `sing-box-bin`: Windows distributes the amd64 core
+and service helper; Linux distributes amd64 and arm64 cores. No additional CPU
+architectures are introduced by the service helper.
+
+### Logs
+
+The service uses the user's sing-box configuration without changing its log level.
+Set `log.level` to `info` or `warn` in that configuration to reduce generated logs.
+`sbc logs --log-level debug` selects the logs to view; it cannot recover debug entries
+that the core did not generate. For diagnostics, explicitly change the core's log level
+and restart, then restore it when finished.
+
+The native Windows host writes only warnings/errors to the Windows Application event
+log (source `sing-box-service-native`). Core stdout/stderr is kept as a bounded diagnostic
+tail for failures, without an additional debug log file. To persist core logs, use
+sing-box's `log.output` configuration; streaming `sbc logs` continues to use the core API.
+Old versioned executables are retained for rollback. After disabling the service,
+its directory under Program Files may be removed manually; user configuration is separate.
+
+## Run
+
+Windows in Admin powershell
+
+```powershell
+sbc --help
+```
+
+Linux
+
+```bash
+sudo sbc --help
+```

sing_box_cli-0.1.2/hatch_build.py

@@ -0,0 +1,47 @@
+"""Bundle the small Windows SCM helper; the CLI remains Python."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel" or version == "editable":
+            return
+        go = shutil.which("go")
+        if go is None:
+            raise RuntimeError(
+                "Building a wheel requires Go (see windows-service/go.mod). Installing a published wheel does not require Go."
+            )
+        root = Path(self.root)
+        output = root / "build" / "windows-service"
+        output.mkdir(parents=True, exist_ok=True)
+        # Match sing-box-bin's single Windows amd64 resource.
+        filename = "sbc-service-windows-amd64.exe"
+        destination = output / filename
+        subprocess.run(
+            [
+                go,
+                "build",
+                "-mod=readonly",
+                "-trimpath",
+                "-ldflags=-s -w",
+                "-o",
+                str(destination),
+                ".",
+            ],
+            cwd=root / "windows-service",
+            env={
+                **os.environ,
+                "GOOS": "windows",
+                "GOARCH": "amd64",
+                "CGO_ENABLED": "0",
+            },
+            check=True,
+        )
+        build_data["force_include"][str(destination)] = f"sing_box_cli/bin/{filename}"

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/pyproject.toml

@@ -39,6 +39,7 @@ Changelog     = "https://github.com/atticuszz/sing-box-service/blob/main/CHANGEL
 
 [project.scripts] # build-backend config needed
 sing-box-cli = "sing_box_cli:main" # equal to from python import main; then run main()
+sbc = "sing_box_cli:main"          # short alias for convenience
 # FROM: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 
 [tool.uv]
@@ -70,6 +71,12 @@ path = "src/sing_box_cli/__init__.py"
 packages = ["src/sing_box_cli"]
 # FROM: https://hatch.pypa.io/latest/build/
 
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/windows-service", "/hatch_build.py", "/pyproject.toml", "/README.md", "/LICENSE"]
+
 ## Test
 [tool.mypy]
 strict              = true
@@ -208,7 +215,7 @@ topo_order = false
 sort_commits = "oldest"
 
 [tool.bumpversion]
-current_version        = "0.1.0"
+current_version        = "0.1.2"
 parse                  = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize              = ["{major}.{minor}.{patch}"]
 search                 = "{current_version}"

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/src/sing_box_cli/__init__.py

@@ -2,4 +2,4 @@ from .main import main
 
 __all__ = ["main"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/src/sing_box_cli/config/config.py

@@ -315,5 +315,17 @@ def get_config() -> ConfigHandler:
     return config
 
 
+def run_args(config: ConfigHandler) -> list[str]:
+    """Build subprocess arguments without splitting paths containing whitespace."""
+    return [
+        str(config.bin_path),
+        "run",
+        "-c",
+        str(config.config_file),
+        "-D",
+        str(config.config_dir),
+    ]
+
+
 def run_cmd(config: ConfigHandler) -> str:
     return f"{config.bin_path} run -c {config.config_file} -D {config.config_dir}"

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/src/sing_box_cli/main.py

@@ -6,7 +6,7 @@ from rich import print
 from sing_box_cli.api import api as api_app
 from sing_box_cli.common import ClearCacheOption, UpdateConfigOption, ensure_root
 from sing_box_cli.config import config as config_app
-from sing_box_cli.config.config import get_config, run_cmd
+from sing_box_cli.config.config import get_config, run_args
 from sing_box_cli.service import SharedContext, get_context_obj, service as service_app
 from sing_box_cli.service.manager import create_service
 
@@ -47,7 +47,7 @@ def run(
         raise typer.Exit(1)
 
     # run
-    cmd = run_cmd(cfg).split()
+    cmd = run_args(cfg)
     subprocess.run(cmd)
 
 

{sing_box_cli-0.1.0 → sing_box_cli-0.1.2}/src/sing_box_cli/service/manager.py

@@ -1,8 +1,7 @@
-import shutil
 import subprocess
 from pathlib import Path
 
-from ..config.config import ConfigHandler, run_cmd
+from ..config.config import ConfigHandler, run_args, run_cmd
 
 
 class ServiceManager:
@@ -35,151 +34,96 @@ class ServiceManager:
 
 
 class WindowsServiceManager(ServiceManager):
-    """
-    commands: https://nssm.cc/commands
-    binary: https://nssm.cc/builds
-    """
+    """Windows SCM service managed by the bundled native Go helper."""
 
     def __init__(self, config: ConfigHandler) -> None:
         super().__init__(config)
         self.service_name = "sing-box-service"
-        self.status_list = ["SERVICE_RUNNING", "SERVICE_STOPPED", "SERVICE_PAUSED"]
 
     @property
-    def nssm_bin(self) -> str:
-        """Get the NSSM executable path"""
-        nssm_exe: Path | str | None = shutil.which("nssm")
-        if nssm_exe is None:
-            bin_dir = Path(__file__).parents[1] / "bin"
-            nssm_exe = bin_dir / "nssm.exe"
-        return str(nssm_exe)
-
-    def create_service(self) -> None:
-        """Create a Windows service using NSSM"""
-        # Install the service
-        try:
-            subprocess.run(
-                [
-                    self.nssm_bin,
-                    "install",
-                    self.service_name,
-                    *run_cmd(self.config).split(),
-                ],
-                check=True,
-                stdout=subprocess.DEVNULL,
+    def helper_bin(self) -> str:
+        # Match sing-box-bin: Windows always ships the amd64 executable.
+        binary = Path(__file__).parents[1] / "bin" / "sbc-service-windows-amd64.exe"
+        if not binary.is_file():
+            raise FileNotFoundError(
+                f"Windows service helper not found: {binary}. Reinstall sing-box-cli from a built wheel."
             )
-        except subprocess.CalledProcessError:
-            # Service might already exist, which is fine for a create
-            pass
+        return str(binary)
 
-        # Automatic startup at boot.
+    def create_service(self) -> None:
+        self.check_service()  # Fail on SCM access errors before attempting installation.
         subprocess.run(
-            [self.nssm_bin, "set", self.service_name, "Start", "SERVICE_AUTO_START"],
+            [
+                self.helper_bin,
+                "install",
+                self.service_name,
+                "--work-dir",
+                str(self.config.config_dir),
+                "--",
+                *run_args(self.config),
+            ],
             check=True,
             stdout=subprocess.DEVNULL,
         )
 
-        # Configure service recovery options
-        subprocess.run(
-            [self.nssm_bin, "set", self.service_name, "AppExit", "Default", "Restart"],
-            check=True,
-            stdout=subprocess.DEVNULL,
+    def check_service(self) -> bool:
+        result = subprocess.run(
+            [self.helper_bin, "exists", self.service_name],
+            capture_output=True,
+            text=True,
         )
+        if result.returncode == 1060:  # ERROR_SERVICE_DOES_NOT_EXIST
+            return False
+        result.check_returncode()
+        return True
 
-        subprocess.run(
-            [self.nssm_bin, "set", self.service_name, "AppRestartDelay", "2000"],
+    def _service_state(self) -> str:
+        result = subprocess.run(
+            [self.helper_bin, "status", self.service_name],
+            capture_output=True,
+            text=True,
             check=True,
-            stdout=subprocess.DEVNULL,
         )
+        return result.stdout.strip()
 
-        # Process priority and CPU affinity
+    def start(self) -> None:
+        if self.check_service() and self._service_state() == "SERVICE_RUNNING":
+            return
         subprocess.run(
-            [
-                self.nssm_bin,
-                "set",
-                self.service_name,
-                "AppPriority",
-                "HIGH_PRIORITY_CLASS",
-            ],
+            [self.helper_bin, "start", self.service_name],
             check=True,
             stdout=subprocess.DEVNULL,
         )
 
-        # A standalone service. This is the default.
+    def stop(self) -> None:
+        if not self.check_service() or self._service_state() == "SERVICE_STOPPED":
+            return
         subprocess.run(
-            [
-                self.nssm_bin,
-                "set",
-                self.service_name,
-                "Type",
-                "SERVICE_WIN32_OWN_PROCESS",
-            ],
+            [self.helper_bin, "stop", self.service_name],
             check=True,
             stdout=subprocess.DEVNULL,
         )
 
-    def check_service(self) -> bool:
-        """Check if the service exists"""
-        result = subprocess.run(
-            [self.nssm_bin, "status", self.service_name], capture_output=True, text=True
-        )
-        return result.stdout.strip() in self.status_list
-
-    def start(self) -> None:
-        """Start the service"""
-        try:
-            subprocess.run(
-                [self.nssm_bin, "start", self.service_name],
-                check=True,
-                stdout=subprocess.DEVNULL,
-            )
-        except subprocess.CalledProcessError:
-            pass
-
-    def stop(self) -> None:
-        """Stop the service"""
-        try:
-            subprocess.run(
-                [self.nssm_bin, "stop", self.service_name],
-                check=True,
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-            )
-        except subprocess.CalledProcessError:
-            # Service might not be running, which is fine for a stop
-            pass
-
     def restart(self) -> None:
-        """Restart the service"""
         subprocess.run(
-            [self.nssm_bin, "restart", self.service_name],
+            [self.helper_bin, "restart", self.service_name],
             check=True,
             stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
         )
 
     def status(self) -> str:
-        """Get the service status"""
-        result = subprocess.run(
-            [self.nssm_bin, "status", self.service_name], capture_output=True, text=True
-        )
-        return (
-            result.stdout.replace("_", " ").title().strip()
-            if result.stdout
-            else "Service not installed"
-        )
+        if not self.check_service():
+            return "Service not installed"
+        return self._service_state().replace("_", " ").title()
 
     def disable(self) -> None:
-        """Remove the service"""
-        try:
-            subprocess.run(
-                [self.nssm_bin, "remove", self.service_name, "confirm"],
-                check=True,
-                stdout=subprocess.DEVNULL,
-            )
-        except subprocess.CalledProcessError:
-            # Service might not exist, which is fine for a disable
-            pass
+        if not self.check_service():
+            return
+        subprocess.run(
+            [self.helper_bin, "remove", self.service_name],
+            check=True,
+            stdout=subprocess.DEVNULL,
+        )
 
     def version(self) -> str:
         result = subprocess.run([self.config.bin_path, "version"], capture_output=True)

sing_box_cli-0.1.2/windows-service/common.go

@@ -0,0 +1,121 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sync"
+)
+
+type invocation struct {
+	command, name, directory string
+	args                     []string
+}
+
+func parseInvocation(args []string) (invocation, error) {
+	var in invocation
+	if len(args) < 2 {
+		return in, errors.New("usage: sbc-service <install|exists|status|start|stop|restart|remove|serve> <service-name> [--work-dir DIR -- PROGRAM ARGS...]")
+	}
+	in.command, in.name = args[0], args[1]
+	if !regexp.MustCompile(`^[A-Za-z0-9_-]+$`).MatchString(in.name) {
+		return in, errors.New("invalid service name")
+	}
+	switch in.command {
+	case "install", "serve":
+		flags := flag.NewFlagSet(in.command, flag.ContinueOnError)
+		flags.SetOutput(io.Discard)
+		flags.StringVar(&in.directory, "work-dir", "", "working directory")
+		if err := flags.Parse(args[2:]); err != nil {
+			return in, err
+		}
+		in.args = flags.Args()
+		if !filepath.IsAbs(in.directory) || len(in.args) == 0 || !filepath.IsAbs(in.args[0]) {
+			return in, errors.New("absolute working directory and executable paths are required")
+		}
+	case "exists", "status", "start", "stop", "restart", "remove":
+		if len(args) != 2 {
+			return in, errors.New("unexpected command arguments")
+		}
+	default:
+		return in, fmt.Errorf("unknown command: %s", in.command)
+	}
+	return in, nil
+}
+
+// Never overwrite an executable that another service or uv environment is using.
+func stageBinary(source, root, filename string) (string, error) {
+	f, err := os.Open(source)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	hash := sha256.New()
+	if _, err := io.Copy(hash, f); err != nil {
+		return "", err
+	}
+	directory := filepath.Join(root, hex.EncodeToString(hash.Sum(nil)))
+	if err := os.MkdirAll(directory, 0755); err != nil {
+		return "", err
+	}
+	destination := filepath.Join(directory, filename)
+	// Verify cached contents too; a partial copy must never become the service target.
+	if data, err := os.ReadFile(destination); err == nil {
+		sum := sha256.Sum256(data)
+		if hex.EncodeToString(sum[:]) == filepath.Base(directory) {
+			return destination, nil
+		}
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return "", err
+	}
+	tmp, err := os.CreateTemp(directory, "copy-*.exe")
+	if err != nil {
+		return "", err
+	}
+	defer os.Remove(tmp.Name())
+	_, copyErr := io.Copy(tmp, f)
+	syncErr := tmp.Sync()
+	closeErr := tmp.Close()
+	if err := errors.Join(copyErr, syncErr, closeErr); err != nil {
+		return "", err
+	}
+	if err := os.Rename(tmp.Name(), destination); err != nil {
+		return "", err
+	}
+	return destination, nil
+}
+
+// Only keep a bounded diagnostic tail, never an unbounded service debug log.
+type diagnosticTail struct {
+	mu   sync.Mutex
+	data []byte
+}
+
+func (t *diagnosticTail) Write(p []byte) (int, error) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	const limit = 8192
+	n := len(p)
+	if len(p) >= limit {
+		t.data = append(t.data[:0], p[len(p)-limit:]...)
+	} else {
+		t.data = append(t.data, p...)
+		if len(t.data) > limit {
+			t.data = t.data[len(t.data)-limit:]
+		}
+	}
+	return n, nil
+}
+
+func (t *diagnosticTail) String() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return string(t.data)
+}