kokorobox-native 0.15.0 → 0.16.1

package/README.md

@@ -1,7 +1,7 @@
 # kokorobox-native
 
-Native Node.js APIs used by KokoroBox Desktop. This package is an ESM loader:
-it selects the native binary for the current operating system and architecture.
+Native Node.js APIs used by KokoroBox Desktop. This ESM package selects the
+native binary for the current operating system and architecture.
 
 ## Installation
 
@@ -9,8 +9,8 @@ it selects the native binary for the current operating system and architecture.
 pnpm add kokorobox-native
 ```
 
-Prebuilt optional packages are available for x64 and arm64 Windows (MSVC),
-macOS, and GNU/Linux. The loader also accepts a development binary through
+Prebuilt optional packages support x64 and arm64 Windows (MSVC), macOS, and
+GNU/Linux. For local development, the loader also accepts
 `NAPI_RS_NATIVE_LIBRARY_PATH`.
 
 ## Usage
@@ -19,125 +19,23 @@ macOS, and GNU/Linux. The loader also accepts a development binary through
 import {
   getNativeCapabilities,
   getNetworkContext,
-  getTrafficPresenterPath,
   inspectApplication,
 } from "kokorobox-native";
 
 const capabilities = getNativeCapabilities();
 const network = await getNetworkContext();
 const app = await inspectApplication("/Applications/KokoroBox.app");
-const presenter = getTrafficPresenterPath();
 ```
 
-The full TypeScript declarations are shipped in
-[`index.d.ts`](index.d.ts).
+Check `getNativeCapabilities()` before using optional platform features.
 
-## API overview
+## Documentation
 
-| Area | Exports |
-| --- | --- |
-| Capabilities | `getNativeCapabilities` |
-| Traffic presenter | `getTrafficPresenterPath` |
-| Icons | `fileToDataUrl`, `getAppName` |
-| Applications | `inspectApplication`, `scanWindowsApplications`, `findExecutables` |
-| Rules | `fileToStr` |
-| Platform | `getLaunchAtLogin`, `setLaunchAtLogin`, `getNetworkContext` |
-| macOS service | `getMacosManagedServiceStatus`, `registerMacosManagedService`, `unregisterMacosManagedService`, `reloadMacosManagedService`, `openMacosLoginItemsSettings` |
-| macOS application routing | `applyMacosApplicationRouting`, `getMacosApplicationRoutingStatus`, `stopMacosApplicationRouting`, `openMacosApplicationRoutingSettings` |
-| Core permissions | `getCorePrivilegeStatus`, `setCorePrivileges` |
-| Privileged operations | `runServiceLifecycleElevated`, `cleanupLegacyMacosService`, `stopMacosManagedService`, `repairManagedFilePermissions` |
-| Windows | `getCurrentUserSid`, `isRunningAsAdmin`, `relaunchCurrentApplicationWithPrivilege`, `ensureKokoroBoxCoreFirewall` |
+- [JavaScript API guide](../docs/api.md)
+- [TypeScript declarations](index.d.ts)
+- [Platform behavior and security contract](../docs/platform-services.md)
+- [Traffic presenter protocol](../docs/traffic-presenter.md)
+- [Repository layout and build commands](../README.md)
 
-`inspectApplication` validates the input for the current platform and resolves
-it to a routing identifier: an executable path on Windows and Linux, or a code
-signing identifier on macOS. `scanWindowsApplications` is asynchronous and
-Windows-only; it accepts an optional result limit and executable-name exclusion
-list.
-
-`findExecutables` asynchronously searches absolute additional directories,
-`PATH`, and platform-standard binary locations without spawning command-line
-tools. It returns canonical paths for stable deduplication; prefix matching is
-available only when explicitly requested.
-
-`ensureKokoroBoxCoreFirewall` accepts the two Mihomo executable paths and the
-KokoroBox application path. Native fixes the three rule names and validates
-the executable basenames before changing Windows Firewall state.
-
-`fileToStr` converts a rule file and returns each generated output keyed by its
-behavior, metadata for those outputs, and rules that were skipped. Its optional
-`RuleConvertOptions` accepts Mihomo, General, Egern, and sing-box targets and
-the formats listed in the TypeScript declaration.
-
-Launch-at-login requires a stable filesystem-safe `identifier`, a display name,
-and an absolute executable path. It returns the selected backend: the Windows
-current-user Run key, macOS `SMAppService.mainApp`, or Linux XDG Autostart. On
-macOS, `requiresApproval` reports when the entry is registered but still needs
-approval in System Settings. Network context is best-effort, so optional fields
-such as the default interface and SSID may be absent. macOS obtains this state
-directly from SystemConfiguration without parsing command output.
-Windows obtains the preferred interface and DNS servers from IP Helper and the
-SSID from Native Wi-Fi, without spawning PowerShell.
-
-The macOS managed-service functions accept the basename of an embedded
-LaunchDaemon plist and use `SMAppService` directly. They return an explicit
-`requires-approval` state when an administrator must approve the daemon in
-System Settings.
-
-The macOS application-routing functions run the bounded control plane off the
-Node.js main thread. Their typed configuration omits fixed protocol details
-such as version, fail-closed behavior, loopback hosts, and reserved ports; the
-native layer owns and validates that wire envelope. Packet forwarding continues
-to run in the separate System Extension process.
-
-Core-file privilege APIs are supported on macOS and Linux. They accept only
-canonical, existing executables named `mihomo` or `mihomo-alpha`; callers cannot
-use them as a general privileged-command interface. See the repository's
-[platform-services contract](../docs/platform-services.md) for validation and
-platform behavior.
-
-`getTrafficPresenterPath()` returns the presenter executable shipped in the
-same platform package as the loaded native binding. The presenter accepts the
-versioned JSON-lines protocol documented by the `traffic-presenter` crate on
-standard input and terminates when its parent closes that stream.
-
-## Platform behavior
-
-Use `getNativeCapabilities()` before enabling an optional system feature.
-Windows account, elevation, Firewall, and application-scan APIs report an
-`UNSUPPORTED_PLATFORM:` error on other operating systems instead of behaving as
-no-ops.
-
-The capability contract includes dedicated flags for APIs that have narrower
-support than the package itself:
-
-| Capability | Supported platforms |
-| --- | --- |
-| `serviceLifecycle` | Windows, macOS, Linux |
-| `managedFilePermissions` | macOS, Linux |
-| `windowsPrivilegeRelaunch` | Windows |
-| `windowsUwpLoopback` | Windows |
-
-Use these flags instead of inferring availability from `process.platform` or
-from a related but broader capability.
-
-`runServiceLifecycleElevated(options)` accepts only the KokoroBox Service
-`init`, `install`, `uninstall`, `start`, `stop`, and `restart` actions. macOS
-legacy-service cleanup, managed-service stopping, and managed-file permission
-repair are separate purpose-specific APIs.
-
-`relaunchCurrentApplicationWithPrivilege(args, elevated)` starts a new copy of
-the current Windows application without accepting an executable path. An
-elevated relaunch presents the standard UAC prompt; the unelevated path uses
-the interactive desktop shell token. It does not configure persistent
-elevation.
-
-## Contributing
-
-The source is a two-crate Rust workspace. The root crate implements native
-behavior; `napi/` maps it into this package’s JavaScript API. See the root
-[README](../README.md#repository-structure) for the complete layout and build
-commands.
-
-This project is derived from
-[`UruhaLushia/sparkle-native`](https://github.com/UruhaLushia/sparkle-native)
-and is licensed under GPL-3.0-only.
+Derived from [UruhaLushia/sparkle-native](https://github.com/UruhaLushia/sparkle-native)
+and licensed under GPL-3.0-only.

package/index.d.ts

@@ -25,12 +25,15 @@ export interface NativeCapabilities {
   serviceLifecycle: boolean;
   managedFilePermissions: boolean;
   macosServiceManagement: boolean;
+  macosServiceProcessStatus: boolean;
   macosApplicationRouting: boolean;
   windowsPrivilegeRelaunch: boolean;
   windowsUwpLoopback: boolean;
+  windowsServiceStatus: boolean;
   coreFilePrivileges: boolean;
   serviceIdentity: boolean;
   linuxTerminalProxy: boolean;
+  linuxServiceStatus: boolean;
 }
 
 export interface ExecutableSearchOptions {
@@ -190,12 +193,18 @@ export function fileToStr(
 ): RuleStringResult;
 export function getAppName(path: string): string;
 export function getNativeCapabilities(): NativeCapabilities;
+/** Read-only status of KokoroBoxService from the Windows Service Control Manager. */
+export function getWindowsServiceStatus(): "running" | "stopped" | "paused" | "not-installed" | "unknown";
+/** Read-only status of the system-wide KokoroBoxService systemd unit. */
+export function getLinuxServiceStatus(): Promise<"running" | "stopped" | "not-installed" | "unknown">;
 /** Write KokoroBox's Linux user-session proxy file and update systemd --user over D-Bus. */
 export function setTerminalProxyEnvironment(host: string, port: number, bypass: string[]): Promise<boolean>;
 /** Remove only KokoroBox's Linux user-session proxy file and clear its session variables. */
 export function clearTerminalProxyEnvironment(): Promise<boolean | null>;
 /** Resolve the executable shipped beside the current platform binding. */
 export function getTrafficPresenterPath(): string;
+/** Resolve the Windows portable updater sidecar shipped with the native platform package. */
+export function getPortableUpdaterPath(): string;
 export function findExecutables(options: ExecutableSearchOptions): Promise<ExecutableCandidate[]>;
 export function getLaunchAtLogin(options: LaunchAtLoginOptions): Promise<LaunchAtLoginStatus>;
 export function setLaunchAtLogin(
@@ -210,6 +219,8 @@ export function waitForNetworkContextChange(
 ): Promise<NetworkContext | null>;
 /** Query a LaunchDaemon plist embedded in the calling macOS application. */
 export function getMacosManagedServiceStatus(plistName: string): MacOSManagedServiceStatus;
+/** Query launchd's process state for the fixed KokoroBoxService system daemon. */
+export function getMacosServiceProcessStatus(): Promise<"running" | "stopped" | "not-installed" | "unknown">;
 export function registerMacosManagedService(plistName: string): MacOSManagedServiceStatus;
 export function unregisterMacosManagedService(plistName: string): MacOSManagedServiceStatus;
 export function reloadMacosManagedService(plistName: string): MacOSManagedServiceStatus;

package/index.js

@@ -59,6 +59,21 @@ export function getTrafficPresenterPath() {
   );
 }
 
+export function getPortableUpdaterPath() {
+  if (process.platform !== "win32") {
+    throw new Error("Portable updater is only available on Windows");
+  }
+  const filename = "kokorobox-portable-updater.exe";
+  const localPath = join(__dirname, filename);
+  if (existsSync(localPath)) return localPath;
+  if (loadedTuple) {
+    const packageEntry = require.resolve(`${packageName}-${loadedTuple}`);
+    const packagedPath = join(dirname(packageEntry), filename);
+    if (existsSync(packagedPath)) return packagedPath;
+  }
+  throw new Error(`Portable updater is missing for ${process.platform} ${process.arch}`);
+}
+
 function requireNative() {
   if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
     try {
@@ -100,6 +115,8 @@ export const fileToDataUrl = nativeBinding.fileToDataUrl;
 export const fileToStr = nativeBinding.fileToStr;
 export const getAppName = nativeBinding.getAppName;
 export const getNativeCapabilities = nativeBinding.getNativeCapabilities;
+export const getWindowsServiceStatus = nativeBinding.getWindowsServiceStatus;
+export const getLinuxServiceStatus = nativeBinding.getLinuxServiceStatus;
 export const setTerminalProxyEnvironment = nativeBinding.setTerminalProxyEnvironment;
 export const clearTerminalProxyEnvironment = nativeBinding.clearTerminalProxyEnvironment;
 export const findExecutables = nativeBinding.findExecutables;
@@ -108,6 +125,7 @@ export const setLaunchAtLogin = nativeBinding.setLaunchAtLogin;
 export const getNetworkContext = nativeBinding.getNetworkContext;
 export const waitForNetworkContextChange = nativeBinding.waitForNetworkContextChange;
 export const getMacosManagedServiceStatus = nativeBinding.getMacosManagedServiceStatus;
+export const getMacosServiceProcessStatus = nativeBinding.getMacosServiceProcessStatus;
 export const registerMacosManagedService = nativeBinding.registerMacosManagedService;
 export const unregisterMacosManagedService = nativeBinding.unregisterMacosManagedService;
 export const reloadMacosManagedService = nativeBinding.reloadMacosManagedService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "KokoroBox native bridge",
   "type": "module",
   "main": "index.js",
@@ -48,11 +48,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "kokorobox-native-win32-x64-msvc": "0.15.0",
-    "kokorobox-native-win32-arm64-msvc": "0.15.0",
-    "kokorobox-native-darwin-x64": "0.15.0",
-    "kokorobox-native-darwin-arm64": "0.15.0",
-    "kokorobox-native-linux-x64-gnu": "0.15.0",
-    "kokorobox-native-linux-arm64-gnu": "0.15.0"
+    "kokorobox-native-win32-x64-msvc": "0.16.1",
+    "kokorobox-native-win32-arm64-msvc": "0.16.1",
+    "kokorobox-native-darwin-x64": "0.16.1",
+    "kokorobox-native-darwin-arm64": "0.16.1",
+    "kokorobox-native-linux-x64-gnu": "0.16.1",
+    "kokorobox-native-linux-arm64-gnu": "0.16.1"
   }
 }