Support macOS SMAppService for login items

Integrate macOS ServiceManagement SMAppService into the LaunchAtLogin implementation and update docs/examples.

Changes:
- src/platform/macos/launch_at_login_macos.mm: Add conditional import for ServiceManagement, gate macOS 13+ SMAppService usage, remove legacy LaunchAgents file plumbing, and implement registration/unregistration via SMAppService. Add helpers (IsCurrentProgram, CanUseConfiguredProgram) and track default id/program to enforce that SMAppService can only register the main app or bundled helper (no arbitrary executable paths or ProgramArguments).
- src/CMakeLists.txt: Link the ServiceManagement framework when building for Apple targets.
- src/launch_at_login.h and src/capi/launch_at_login_c.h: Update API docs to note macOS SMAppService behavior and limitations (no arbitrary executable paths/arguments for main-app login items).
- examples/*: Update C and C++ examples to use the default constructor on macOS (which registers the main app) and avoid setting program/arguments on macOS where not supported.

Reasoning: On modern macOS (13+), SMAppService is the supported API for login items and does not accept arbitrary program paths or ProgramArguments for the main app; this change adopts SMAppService where available, documents the platform limitations, and prevents attempts to register unsupported configurations.

Author: lijy91

examples/launch_at_login_c_example/main.c

@@ -14,9 +14,17 @@ int main(void) {
 
   printf("LaunchAtLogin is supported on this platform.\n\n");
 
+#if defined(__APPLE__)
+  /*
+   * On macOS, the default constructor registers the main app with SMAppService.
+   * Custom identifiers are for bundled login item helpers.
+   */
+  native_launch_at_login_t launch_at_login = native_launch_at_login_create();
+#else
   /* Create a LaunchAtLogin manager with a custom identifier and display name */
   native_launch_at_login_t launch_at_login =
       native_launch_at_login_create_with_id_and_name("com.example.myapp.c", "My C Example App");
+#endif
   if (!launch_at_login) {
     printf("Failed to create LaunchAtLogin instance.\n");
     return 1;
@@ -35,16 +43,22 @@ int main(void) {
   free_c_str(id);
   free_c_str(display_name);
 
+#if !defined(__APPLE__)
   /* Set a custom program path and arguments */
   const char* arguments[] = {"--minimized", "--launch_at_login"};
   native_launch_at_login_set_program(launch_at_login, executable ? executable : "", arguments, 2);
+#endif
   free_c_str(executable);
 
   /* Retrieve and display the updated executable path */
   char* exec_path = native_launch_at_login_get_executable_path(launch_at_login);
   printf("After SetProgram:\n");
   printf("  Executable: %s\n", exec_path ? exec_path : "(null)");
+#if defined(__APPLE__)
+  printf("  Arguments:  (not supported by macOS SMAppService main-app login items)\n\n");
+#else
   printf("  Arguments:  --minimized --launch_at_login\n\n");
+#endif
   free_c_str(exec_path);
 
   /* Check current state before enabling */

examples/launch_at_login_example/main.cpp

@@ -18,18 +18,26 @@ int main() {
 
   std::cout << "LaunchAtLogin is supported on this platform.\n\n";
 
-  // Create a LaunchAtLogin manager with a custom identifier and display name
+  // On macOS, the default constructor registers the main app with SMAppService.
+  // Custom identifiers are for bundled login item helpers.
+#if defined(__APPLE__)
+  LaunchAtLogin launch_at_login;
+#else
   LaunchAtLogin launch_at_login("com.example.myapp", "My Example App");
+#endif
 
   // Display current configuration
   std::cout << "LaunchAtLogin configuration:\n";
   std::cout << "  ID:           " << launch_at_login.GetId() << "\n";
   std::cout << "  Display name: " << launch_at_login.GetDisplayName() << "\n";
   std::cout << "  Executable:   " << launch_at_login.GetExecutablePath() << "\n\n";
 
+// macOS SMAppService main-app login items do not support arbitrary arguments.
+#if !defined(__APPLE__)
   // Set a custom program path and arguments
   launch_at_login.SetProgram(launch_at_login.GetExecutablePath(),
                              {"--minimized", "--launch_at_login"});
+#endif
 
   std::cout << "After SetProgram:\n";
   std::cout << "  Executable: " << launch_at_login.GetExecutablePath() << "\n";

src/CMakeLists.txt

@@ -76,6 +76,7 @@ elseif (CMAKE_SYSTEM_NAME STREQUAL "Linux")
 elseif(APPLE)
     target_link_libraries(nativeapi PUBLIC "-framework Cocoa")
     target_link_libraries(nativeapi PUBLIC "-framework Carbon")
+    target_link_libraries(nativeapi PUBLIC "-framework ServiceManagement")
     target_compile_options(nativeapi PRIVATE "-x" "objective-c++")
 elseif(CMAKE_SYSTEM_NAME STREQUAL "OHOS")
     target_link_libraries(nativeapi PUBLIC hilog_ndk.z)

src/capi/launch_at_login_c.h

@@ -17,7 +17,7 @@ extern "C" {
  *
  * Platform behavior:
  * - Windows: HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry value
- * - macOS:   Launch Agents in ~/Library/LaunchAgents (plist with ProgramArguments)
+ * - macOS:   ServiceManagement SMAppService for the main app or bundled login item helpers
  * - Linux:   XDG autostart in ~/.config/autostart (Desktop Entry Exec line)
  * - Mobile (Android/iOS/OHOS): Typically unsupported (functions return false)
  *
@@ -106,6 +106,8 @@ bool native_launch_at_login_set_display_name(native_launch_at_login_t launch_at_
  *
  * If not set, the implementation attempts to use the current process executable.
  * Pass NULL for arguments or argument_count == 0 when no arguments are needed.
+ * On macOS, SMAppService does not support arbitrary executable paths or arguments for
+ * main-app login items.
  *
  * @param launch_at_login       LaunchAtLogin handle.
  * @param executable_path Absolute path to the executable to launch on login.

src/launch_at_login.h

@@ -15,15 +15,18 @@ namespace nativeapi {
  *
  * Platform implementations:
  * - Windows: HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry key
- * - macOS: Launch Agents (~/Library/LaunchAgents/[app_id].plist) with ProgramArguments
+ * - macOS: ServiceManagement SMAppService for the main app or bundled login item helpers
  * - Linux (XDG): ~/.config/autostart/[app_id].desktop
  * - Android/iOS/OHOS: Not supported (returns false from IsSupported/operations)
  *
  * Notes:
  * - This API is intended for desktop environments. On mobile platforms this API is
  *   typically unsupported by design. Methods will fail gracefully.
  * - You can let the implementation determine the current executable path, or call
- *   SetProgram() to customize the target binary and arguments recorded in the OS.
+ *   SetProgram() to customize the target binary and arguments recorded in the OS where the
+ *   platform supports arbitrary launch commands. On macOS, SMAppService can only register
+ *   the main app or a bundled helper, so custom executable paths and arguments are not
+ *   supported.
  * - Some platforms may require application-specific permissions or entitlements
  *   (e.g., sandbox restrictions on macOS). In such cases, operations may fail.
  *
@@ -33,7 +36,7 @@ namespace nativeapi {
  *
  * if (LaunchAtLogin::IsSupported()) {
  *   LaunchAtLogin launch_at_login("com.example.myapp", "MyApp");
- *   // Optionally override the program and arguments (defaults to current executable):
+ *   // Optionally override the program and arguments where supported:
  *   launch_at_login.SetProgram("/usr/local/bin/myapp", {"--minimized"});
  *
  *   launch_at_login.Enable();
@@ -65,7 +68,8 @@ class LaunchAtLogin {
    * @param id A stable, unique identifier for your app.
    *           Examples:
    *           - Windows: used as the registry value name, e.g., "MyApp"
-   *           - macOS: used as LaunchAgent Label, e.g., "com.example.myapp"
+   *           - macOS: bundle identifier for a bundled LoginItem helper, e.g.,
+   *             "com.example.myapp.Helper"; the default constructor registers the main app
    *           - Linux: used as the .desktop file name (without extension), e.g., "myapp"
    *
    * Recommendation: Use a reverse-DNS identifier when possible, e.g., "com.example.myapp".
@@ -99,8 +103,7 @@ class LaunchAtLogin {
   /**
    * @brief Set a human-readable display name used where applicable.
    *
-   * Some platforms surface a name in their UI (e.g., Linux .desktop Name, macOS LaunchAgent Label
-   * often mirrors the identifier but may display the name in some tools).
+   * Some platforms surface a name in their UI (e.g., Linux .desktop Name).
    *
    * @param display_name The human-readable name.
    * @return true if the value was stored locally; does not change OS registration until Enable().
@@ -112,8 +115,9 @@ class LaunchAtLogin {
    *
    * If not set, implementations will try to use the current process executable path.
    * On platforms that require a single string (e.g., Windows registry), arguments will
-   * be encoded appropriately (quoted when needed). On macOS/Linux, arguments are stored
-   * as vector items (.plist ProgramArguments / .desktop Exec respectively).
+   * be encoded appropriately (quoted when needed). On Linux, arguments are stored in
+   * the .desktop Exec line. On macOS, SMAppService does not support arbitrary
+   * executable paths or arguments for main-app login items.
    *
    * @param executable_path Absolute path to the executable to run on login.
    * @param arguments       Optional arguments; order is preserved.