Skip to content

CLI for SidePulse

Python

Give macOS background service a SidePulse display name

Peter Kuhar6d55225fed20
diff --git a/README.md b/README.md
index f56a314..95f90f3 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,8 @@ uses CLI-only mode for mounted SidePulse devices and iPhone linking/push. Run
`sidepulse update` to upgrade to the newest version from GitHub.
Setup also installs a headless SidePulse service. It runs through a LaunchAgent
-on macOS and a user systemd service on Linux. Setup restarts the service, so an
+named **SidePulse Background Service** in macOS background activity settings,
+and a user systemd service on Linux. Setup restarts the service, so an
upgrade takes effect right away instead of leaving the previous build running.
If a Linux session has no systemd user manager, setup still installs the unit
and prints that it could not start; `sidepulse service run` remains available as
diff --git a/src/sidepulse/service_launch.py b/src/sidepulse/service_launch.py
index 5cec58b..063e3ab 100644
--- a/src/sidepulse/service_launch.py
+++ b/src/sidepulse/service_launch.py
@@ -2,6 +2,7 @@ from __future__ import annotations
import os
import plistlib
+import shlex
import shutil
import subprocess
import sys
@@ -12,6 +13,7 @@ from .providers import default_state_dir
SERVICE_LABEL = "io.sidepulse.service"
+SERVICE_DISPLAY_NAME = "SidePulse Background Service"
@dataclass(frozen=True)
@@ -23,9 +25,22 @@ class ServiceInstallResult:
def service_command() -> list[str]:
+ if getattr(sys, "frozen", False):
+ return [sys.executable, "service", "run"]
return [sys.executable, "-m", "sidepulse", "service", "run"]
+def service_launcher_path() -> Path:
+ data_home = os.environ.get("XDG_DATA_HOME")
+ base = Path(data_home).expanduser() if data_home else Path.home() / ".local" / "share"
+ return base / "sidepulse" / "service" / SERVICE_DISPLAY_NAME
+
+
+def build_service_launcher_script() -> str:
+ command = " ".join(shlex.quote(part) for part in service_command())
+ return f"#!/bin/sh\nexport PYTHONUNBUFFERED=1\nexec {command}\n"
+
+
def install_service(*, start: bool = True, dry_run: bool = False) -> ServiceInstallResult:
if sys.platform == "darwin":
return install_launch_agent(start=start, dry_run=dry_run)
@@ -37,9 +52,13 @@ def install_service(*, start: bool = True, dry_run: bool = False) -> ServiceInst
def install_launch_agent(*, start: bool, dry_run: bool) -> ServiceInstallResult:
path = Path.home() / "Library" / "LaunchAgents" / f"{SERVICE_LABEL}.plist"
state = default_state_dir()
+ launcher = service_launcher_path()
+ launcher_data = build_service_launcher_script().encode()
payload = {
"Label": SERVICE_LABEL,
- "ProgramArguments": service_command(),
+ # macOS names unbundled background items after the registered program.
+ # Register our launcher rather than the shared Python interpreter.
+ "ProgramArguments": [str(launcher)],
"RunAtLoad": True,
"KeepAlive": True,
"StandardOutPath": str(state / "service.out.log"),
@@ -54,12 +73,18 @@ def install_launch_agent(*, start: bool, dry_run: bool) -> ServiceInstallResult:
}
data = plistlib.dumps(payload, sort_keys=False)
existing = path.read_bytes() if path.exists() else None
- changed = existing != data
+ existing_launcher = launcher.read_bytes() if launcher.exists() else None
+ launcher_changed = existing_launcher != launcher_data or not os.access(launcher, os.X_OK)
+ changed = existing != data or launcher_changed
if dry_run:
return ServiceInstallResult(path, changed, False, "dry run")
path.parent.mkdir(parents=True, exist_ok=True)
state.mkdir(parents=True, exist_ok=True)
- if changed:
+ launcher.parent.mkdir(parents=True, exist_ok=True)
+ if launcher_changed:
+ launcher.write_bytes(launcher_data)
+ launcher.chmod(0o755)
+ if existing != data:
path.write_bytes(data)
started = False
if start:
diff --git a/tests/test_service_launch.py b/tests/test_service_launch.py
new file mode 100644
index 0000000..7a2edc3
--- /dev/null
+++ b/tests/test_service_launch.py
@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import os
+import plistlib
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from sidepulse.service_launch import (
+ SERVICE_DISPLAY_NAME,
+ SERVICE_LABEL,
+ build_service_launcher_script,
+ install_launch_agent,
+ service_command,
+)
+
+
+class MacServiceLaunchTests(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory(prefix="sidepulse-service-test-")
+ self.addCleanup(self.tmp.cleanup)
+ self.home = Path(self.tmp.name) / "home with spaces"
+ self.launcher = self.home / "data/service" / SERVICE_DISPLAY_NAME
+ self.patch_home = patch.object(Path, "home", return_value=self.home)
+ self.patch_home.start()
+ self.addCleanup(self.patch_home.stop)
+ self.patch_launcher = patch(
+ "sidepulse.service_launch.service_launcher_path", return_value=self.launcher,
+ )
+ self.patch_launcher.start()
+ self.addCleanup(self.patch_launcher.stop)
+ self.patch_state = patch(
+ "sidepulse.service_launch.default_state_dir", return_value=self.home / "state",
+ )
+ self.patch_state.start()
+ self.addCleanup(self.patch_state.stop)
+
+ def test_existing_python_agent_migrates_to_named_launcher(self):
+ target = self.home / "Library/LaunchAgents" / f"{SERVICE_LABEL}.plist"
+ target.parent.mkdir(parents=True)
+ target.write_bytes(plistlib.dumps({
+ "Label": SERVICE_LABEL, "ProgramArguments": service_command(),
+ }))
+ with (
+ patch("sidepulse.service_launch.subprocess.check_output", return_value="123\n"),
+ patch("sidepulse.service_launch.subprocess.run", return_value=SimpleNamespace(returncode=0, stderr="")) as run,
+ ):
+ result = install_launch_agent(start=True, dry_run=False)
+
+ self.assertTrue(result.changed)
+ self.assertTrue(result.started)
+ payload = plistlib.loads(target.read_bytes())
+ self.assertEqual(payload["Label"], SERVICE_LABEL)
+ self.assertEqual(payload["ProgramArguments"], [str(self.launcher)])
+ self.assertTrue(payload["KeepAlive"])
+ self.assertTrue(os.access(self.launcher, os.X_OK))
+ self.assertEqual([call.args[0][:2] for call in run.call_args_list], [
+ ["launchctl", "bootout"], ["launchctl", "bootstrap"],
+ ])
+
+ def test_launcher_executes_original_service_command_with_spaces(self):
+ interpreter = self.home / "python with spaces"
+ interpreter.parent.mkdir(parents=True)
+ interpreter.write_text(
+ f"#!{sys.executable}\nimport json, sys\nprint(json.dumps(sys.argv[1:]))\n"
+ )
+ interpreter.chmod(0o755)
+ with patch("sidepulse.service_launch.sys.executable", str(interpreter)):
+ install_launch_agent(start=False, dry_run=False)
+ result = subprocess.run([str(self.launcher)], capture_output=True, text=True, check=True)
+ self.assertEqual(json.loads(result.stdout), ["-m", "sidepulse", "service", "run"])
+
+ def test_dry_run_writes_no_launcher_or_plist(self):
+ result = install_launch_agent(start=True, dry_run=True)
+ self.assertTrue(result.changed)
+ self.assertFalse(result.started)
+ self.assertFalse(self.home.exists())
+
+ def test_reinstall_is_unchanged_and_repairs_missing_launcher(self):
+ install_launch_agent(start=False, dry_run=False)
+ self.assertFalse(install_launch_agent(start=False, dry_run=False).changed)
+ self.launcher.unlink()
+ self.assertTrue(install_launch_agent(start=False, dry_run=False).changed)
+ self.assertTrue(os.access(self.launcher, os.X_OK))
+
+ def test_reinstall_repairs_launcher_permissions(self):
+ install_launch_agent(start=False, dry_run=False)
+ self.launcher.chmod(0o644)
+ self.assertTrue(install_launch_agent(start=False, dry_run=False).changed)
+ self.assertTrue(os.access(self.launcher, os.X_OK))
+
+ def test_frozen_service_uses_application_cli(self):
+ with patch("sidepulse.service_launch.sys.frozen", True, create=True):
+ self.assertEqual(service_command(), [sys.executable, "service", "run"])
+ self.assertNotIn("-m sidepulse", build_service_launcher_script())