kokorobox-native 0.16.1 → 0.16.3

package/README.md

@@ -29,6 +29,38 @@ const app = await inspectApplication("/Applications/KokoroBox.app");
 
 Check `getNativeCapabilities()` before using optional platform features.
 
+## Diagnostics
+
+`drainNativeLogs()` returns English JSON-compatible records with `ts`, `level`,
+`target`, and `msg`. Use one consumer to periodically drain the queue into the
+application's log. It retains at most 500 records; overflow produces a warning.
+`setNativeLogLevel("debug" | "info" | "warn" | "error")` changes recording
+severity (default: `info`). Healthy polling is only recorded at `debug`. Operation failures retain
+their original exceptions and causes; lifecycle successes record the operation
+name without arguments, keys, or signatures.
+
+The traffic presenter emits JSON Lines to stderr. The Windows portable updater
+also saves its last run in `%TEMP%/kokorobox-portable-updater.log` because Desktop
+exits before extraction. These sidecars include Unix milliseconds in `timestamp`.
+
+## System Proxy diagnostics
+
+`getSystemProxyDiagnostics()` returns actual OS configuration with independent
+availability information. Windows, macOS and Linux share the same entry point;
+platform-specific details are nested under `windows`, `macos` or `linux`.
+macOS uses SystemConfiguration for effective HTTP/HTTPS/SOCKS, PAC/discovery,
+primary IPv4/IPv6 services and the current Network Location. Reading never asks
+for administrator authorization. Runtime health and connectivity belong to
+KokoroBox Service, not this API.
+
+`setSystemProxy(settings)` supports explicit Windows/macOS manual, PAC and
+disabled actions. macOS honors `onlyActiveDevice`, preserves PAC/discovery
+when restoring manual proxies, and reuses Native's administrator dialog if
+required for a write. Its structured result includes
+`automaticSettingsPreserved`; callers must not resume a legacy watchdog or
+cleanup that would erase those settings. Never invoke this setter merely to
+inspect or refresh diagnostics.
+
 ## Documentation
 
 - [JavaScript API guide](../docs/api.md)

package/diagnostics.js

@@ -0,0 +1,144 @@
+// Diagnostics belong to the calling application. Do not open a log file or
+// retain operation arguments (which may contain keys or signatures).
+const maxEntries = 500;
+const maxMessageLength = 4096;
+const levels = ["debug", "info", "warn", "error"];
+const lifecycleOperations = new Set([
+  "runServiceLifecycleElevated",
+  "registerMacosManagedService",
+  "unregisterMacosManagedService",
+  "reloadMacosManagedService",
+  "cleanupLegacyMacosService",
+  "stopMacosManagedService",
+  "repairManagedFilePermissions",
+  "setCorePrivileges",
+  "applyMacosApplicationRouting",
+  "stopMacosApplicationRouting",
+  "setLaunchAtLogin",
+  "setUwpLoopbackExemption",
+  "setSystemProxy",
+]);
+
+function boundedMessage(value) {
+  const text = String(value);
+  if (text.length <= maxMessageLength) return text;
+  let end = maxMessageLength;
+  if (/^[\uDC00-\uDFFF]$/.test(text[end])) end--;
+  return text.slice(0, end) + "…";
+}
+
+export function nativeErrorMessage(error) {
+  const parts = [];
+  const seen = new Set();
+  function visit(value, depth = 0) {
+    if (depth > 4 || seen.has(value)) return;
+    seen.add(value);
+    const message = value instanceof Error ? value.message : String(value);
+    if (message && !parts.includes(message))
+      parts.push(boundedMessage(message));
+    if (value && typeof value === "object" && value.cause != null) {
+      if (Array.isArray(value.cause))
+        value.cause.slice(0, 4).forEach((item) => visit(item, depth + 1));
+      else visit(value.cause, depth + 1);
+    }
+  }
+  visit(error);
+  return boundedMessage(parts.join(": "));
+}
+
+export function createNativeDiagnostics() {
+  let minimum = "info";
+  let entries = [];
+  let dropped = 0;
+  const record = (level, target, msg) => {
+    if (levels.indexOf(level) < levels.indexOf(minimum)) return;
+    entries.push({
+      ts: new Date().toISOString(),
+      level,
+      target,
+      msg: boundedMessage(msg),
+    });
+    if (entries.length > maxEntries) {
+      entries.shift();
+      dropped++;
+    }
+  };
+  return {
+    setLevel(level) {
+      if (!levels.includes(level))
+        throw new TypeError(
+          "Invalid Native log level: expected debug, info, warn, or error",
+        );
+      minimum = level;
+    },
+    drain() {
+      const result = entries;
+      entries = [];
+      if (dropped) {
+        result.unshift({
+          ts: new Date().toISOString(),
+          level: "warn",
+          target: "diagnostics",
+          msg: `Dropped ${dropped} older Native log entries`,
+        });
+        dropped = 0;
+      }
+      return result;
+    },
+    wrap(target, operation) {
+      if (typeof operation !== "function") return operation;
+      const failed = (error) => {
+        record("error", target, nativeErrorMessage(error));
+        throw error;
+      };
+      const completed = (value) => {
+        if (target === "getSystemProxyDiagnostics") {
+          record(value.status === "available" ? "info" : "warn", "SystemProxy", `[SystemProxy] Configuration: ${value.status}; Proxy enabled: ${value.enabled ?? "unknown"}`);
+          if (value.macos) {
+            const effective = value.macos.effective;
+            const count = value.macos.activeServiceIds?.length ?? 0;
+            record("info", "SystemProxy", `[SystemProxy/macOS] Active network services: ${count}; HTTP: ${effective?.http?.enabled ?? "unknown"}; HTTPS: ${effective?.https?.enabled ?? "unknown"}; PAC: ${effective?.pacEnabled ?? "unknown"}; Auto discovery: ${effective?.autoDiscovery ?? "unknown"}`);
+          }
+          if (value.linux) {
+            const backend = ["gnome", "kde", "environment", "unsupported"].includes(value.linux.backend) ? value.linux.backend : "unknown";
+            const portal = value.linux.portal?.status === "available" ? "available" : "unavailable";
+            record("info", "SystemProxy", `[SystemProxy] Linux backend: ${backend}; Portal: ${portal}`);
+          }
+          if (value.pac?.enabled) record("info", "SystemProxy", "[SystemProxy] PAC configuration detected");
+          for (const [name, state] of Object.entries({winHttp: value.windows?.winHttp, appContainer: value.windows?.appContainer})) {
+            if (state?.status === "unavailable") record("warn", "SystemProxy", `[SystemProxy] ${name}: unavailable`);
+          }
+          return value;
+        }
+        if (value && value.state === "error")
+          record(
+            "error",
+            target,
+            typeof value.message === "string"
+              ? value.message
+              : "Native operation returned an error status",
+          );
+        else if (lifecycleOperations.has(target))
+          record("info", target, "Native operation completed");
+        else record("debug", target, "Native operation completed");
+        return value;
+      };
+      return function (...args) {
+        let result;
+        try {
+          result = Reflect.apply(operation, this, args);
+        } catch (error) {
+          return failed(error);
+        }
+        if (result && typeof result.then === "function")
+          return result.then(completed, failed);
+        return completed(result);
+      };
+    },
+  };
+}
+
+const diagnostics = createNativeDiagnostics();
+export const wrapNativeOperation = diagnostics.wrap;
+export const drainNativeLogs = diagnostics.drain;
+export const setNativeLogLevel = diagnostics.setLevel;

package/index.d.ts

@@ -1,3 +1,14 @@
+export interface NativeLogEntry {
+  ts: string;
+  level: "debug" | "info" | "warn" | "error";
+  target: string;
+  msg: string;
+}
+/** Drains at most 500 entries and an optional overflow warning; use one consumer. */
+export declare function drainNativeLogs(): NativeLogEntry[];
+/** Controls recording, independently from display language. Defaults to info. */
+export declare function setNativeLogLevel(level: NativeLogEntry["level"]): void;
+
 export interface UwpLoopbackApp {
   /** Opaque identifier used only when changing this app's loopback exemption. */
   id: string;
@@ -314,3 +325,94 @@ export function ensureKokoroBoxCoreFirewall(
 ): void;
 export function listUwpLoopbackApps(): UwpLoopbackApp[];
 export function setUwpLoopbackExemption(id: string, enabled: boolean): void;
+
+export interface NativeProxyEndpoint {
+  host: string;
+  port: number;
+}
+export interface MacProxyProtocol {
+  enabled: boolean;
+  endpoint?: NativeProxyEndpoint | null;
+}
+export interface MacProxyState {
+  http: MacProxyProtocol;
+  https: MacProxyProtocol;
+  socks: MacProxyProtocol;
+  pacEnabled: boolean;
+  pacUrl?: string | null;
+  autoDiscovery: boolean;
+  bypass: string[];
+  excludeSimpleHostnames: boolean;
+}
+export interface MacNetworkService {
+  id: string;
+  name: string;
+  interface?: string | null;
+  enabled: boolean;
+  active: boolean;
+  primary: boolean;
+  status: "available" | "unavailable";
+  proxies?: MacProxyState | null;
+}
+export interface MacOSProxyDetails {
+  effective?: MacProxyState | null;
+  activeServiceIds: string[];
+  services: MacNetworkService[];
+  networkLocation?: string | null;
+  locationErrorCode?: string | null;
+  serviceErrorCode?: string | null;
+}
+export interface NativeSystemProxyMutation {
+  automaticSettingsPreserved: boolean;
+}
+export interface NativeSystemProxyDiagnostics {
+  platform: "windows" | "darwin" | "linux";
+  status: "available" | "unavailable" | "unsupported";
+  errorCode?: string | null;
+  enabled?: boolean | null;
+  proxies: {
+    http?: NativeProxyEndpoint | null;
+    https?: NativeProxyEndpoint | null;
+    socks?: NativeProxyEndpoint | null;
+  };
+  pac?: { enabled: boolean; url?: string | null } | null;
+  bypass: string[];
+  macos?: MacOSProxyDetails | null;
+  linux?: {
+    desktopEnvironment: string;
+    backend: "gnome" | "kde" | "environment" | "unsupported";
+    mode?: "none" | "manual" | "auto" | "wpad" | "environment" | null;
+    reversedBypass: boolean;
+    environment: { name: string; endpoint?: NativeProxyEndpoint | null; bypass: string[]; valid: boolean }[];
+    portal: { status: "available" | "unavailable"; direct: boolean; proxies: NativeProxyEndpoint[]; errorCode?: string | null };
+  } | null;
+  windows?: {
+    proxyServer?: string | null;
+    proxyOverride?: string | null;
+    autoConfigUrl?: string | null;
+    winHttp: {
+      status: "available" | "unavailable";
+      mode?: "direct" | "proxy" | "advanced" | null;
+      proxy?: string | null;
+      bypass?: string | null;
+      errorCode?: string | null;
+    };
+    appContainer: {
+      supported: boolean;
+      status: "available" | "unavailable";
+      loopbackExemptionCount?: number | null;
+      errorCode?: string | null;
+    };
+  } | null;
+}
+export interface NativeSystemProxySettings {
+  mode: "manual" | "auto" | "disabled";
+  host?: string;
+  port?: number;
+  bypass: string[];
+  pacUrl?: string;
+  onlyActiveDevice?: boolean;
+}
+export declare function getSystemProxyDiagnostics(): Promise<NativeSystemProxyDiagnostics>;
+/** Explicit user action only. Leaves WinHTTP/UWP unchanged; macOS manual restore preserves PAC/discovery. */
+export declare function setSystemProxy(settings: NativeSystemProxySettings): Promise<NativeSystemProxyMutation>;

package/index.js

@@ -5,6 +5,13 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
+import {
+  nativeErrorMessage,
+  wrapNativeOperation,
+  drainNativeLogs,
+  setNativeLogLevel,
+} from "./diagnostics.js";
+export { drainNativeLogs, setNativeLogLevel };
 
 const require = createRequire(import.meta.url);
 const __dirname = new URL(".", import.meta.url).pathname.replace(
@@ -71,7 +78,9 @@ export function getPortableUpdaterPath() {
     const packagedPath = join(dirname(packageEntry), filename);
     if (existsSync(packagedPath)) return packagedPath;
   }
-  throw new Error(`Portable updater is missing for ${process.platform} ${process.arch}`);
+  throw new Error(
+    `Portable updater is missing for ${process.platform} ${process.arch}`,
+  );
 }
 
 function requireNative() {
@@ -105,49 +114,91 @@ function requireNative() {
 const nativeBinding = requireNative();
 
 if (!nativeBinding) {
-  const error = new Error("Failed to load kokorobox-native binding");
+  const detail = nativeErrorMessage({
+    cause: loadErrors,
+    toString: () => "Failed to load kokorobox-native binding",
+  });
+  const error = new Error(detail);
   error.cause = loadErrors;
   throw error;
 }
 
-export default nativeBinding;
-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;
-export const getLaunchAtLogin = nativeBinding.getLaunchAtLogin;
-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;
-export const openMacosLoginItemsSettings = nativeBinding.openMacosLoginItemsSettings;
-export const applyMacosApplicationRouting = nativeBinding.applyMacosApplicationRouting;
-export const getMacosApplicationRoutingStatus = nativeBinding.getMacosApplicationRoutingStatus;
-export const stopMacosApplicationRouting = nativeBinding.stopMacosApplicationRouting;
-export const openMacosApplicationRoutingSettings = nativeBinding.openMacosApplicationRoutingSettings;
-export const runServiceLifecycleElevated = nativeBinding.runServiceLifecycleElevated;
-export const cleanupLegacyMacosService = nativeBinding.cleanupLegacyMacosService;
-export const stopMacosManagedService = nativeBinding.stopMacosManagedService;
-export const repairManagedFilePermissions = nativeBinding.repairManagedFilePermissions;
-export const relaunchCurrentApplicationWithPrivilege = nativeBinding.relaunchCurrentApplicationWithPrivilege;
-export const getCorePrivilegeStatus = nativeBinding.getCorePrivilegeStatus;
-export const setCorePrivileges = nativeBinding.setCorePrivileges;
-export const inspectApplication = nativeBinding.inspectApplication;
-export const scanWindowsApplications = nativeBinding.scanWindowsApplications;
-export const getCurrentUserSid = nativeBinding.getCurrentUserSid;
-export const isRunningAsAdmin = nativeBinding.isRunningAsAdmin;
-export const ensureKokoroBoxCoreFirewall = nativeBinding.ensureKokoroBoxCoreFirewall;
-export const listUwpLoopbackApps = nativeBinding.listUwpLoopbackApps;
-export const setUwpLoopbackExemption = nativeBinding.setUwpLoopbackExemption;
-export const ServiceIdentity = nativeBinding.ServiceIdentity;
-export const openServiceIdentity = nativeBinding.openServiceIdentity;
-export const deleteServiceIdentity = nativeBinding.deleteServiceIdentity;
+// Preserve native classes and unsupported exports; wrap callable operations
+// for both named imports and the default binding without changing arguments.
+const diagnosticBinding = {};
+for (const [name, descriptor] of Object.entries(
+  Object.getOwnPropertyDescriptors(nativeBinding),
+)) {
+  if (/^[a-z]/.test(name) && typeof descriptor.value === "function") {
+    descriptor.value = wrapNativeOperation(name, descriptor.value);
+  }
+  Object.defineProperty(diagnosticBinding, name, descriptor);
+}
+diagnosticBinding.drainNativeLogs = drainNativeLogs;
+diagnosticBinding.setNativeLogLevel = setNativeLogLevel;
+export default diagnosticBinding;
+export const fileToDataUrl = diagnosticBinding.fileToDataUrl;
+export const fileToStr = diagnosticBinding.fileToStr;
+export const getAppName = diagnosticBinding.getAppName;
+export const getNativeCapabilities = diagnosticBinding.getNativeCapabilities;
+export const getWindowsServiceStatus =
+  diagnosticBinding.getWindowsServiceStatus;
+export const getLinuxServiceStatus = diagnosticBinding.getLinuxServiceStatus;
+export const setTerminalProxyEnvironment =
+  diagnosticBinding.setTerminalProxyEnvironment;
+export const clearTerminalProxyEnvironment =
+  diagnosticBinding.clearTerminalProxyEnvironment;
+export const findExecutables = diagnosticBinding.findExecutables;
+export const getLaunchAtLogin = diagnosticBinding.getLaunchAtLogin;
+export const setLaunchAtLogin = diagnosticBinding.setLaunchAtLogin;
+export const getNetworkContext = diagnosticBinding.getNetworkContext;
+export const waitForNetworkContextChange =
+  diagnosticBinding.waitForNetworkContextChange;
+export const getMacosManagedServiceStatus =
+  diagnosticBinding.getMacosManagedServiceStatus;
+export const getMacosServiceProcessStatus =
+  diagnosticBinding.getMacosServiceProcessStatus;
+export const registerMacosManagedService =
+  diagnosticBinding.registerMacosManagedService;
+export const unregisterMacosManagedService =
+  diagnosticBinding.unregisterMacosManagedService;
+export const reloadMacosManagedService =
+  diagnosticBinding.reloadMacosManagedService;
+export const openMacosLoginItemsSettings =
+  diagnosticBinding.openMacosLoginItemsSettings;
+export const applyMacosApplicationRouting =
+  diagnosticBinding.applyMacosApplicationRouting;
+export const getMacosApplicationRoutingStatus =
+  diagnosticBinding.getMacosApplicationRoutingStatus;
+export const stopMacosApplicationRouting =
+  diagnosticBinding.stopMacosApplicationRouting;
+export const openMacosApplicationRoutingSettings =
+  diagnosticBinding.openMacosApplicationRoutingSettings;
+export const runServiceLifecycleElevated =
+  diagnosticBinding.runServiceLifecycleElevated;
+export const cleanupLegacyMacosService =
+  diagnosticBinding.cleanupLegacyMacosService;
+export const stopMacosManagedService =
+  diagnosticBinding.stopMacosManagedService;
+export const repairManagedFilePermissions =
+  diagnosticBinding.repairManagedFilePermissions;
+export const relaunchCurrentApplicationWithPrivilege =
+  diagnosticBinding.relaunchCurrentApplicationWithPrivilege;
+export const getCorePrivilegeStatus = diagnosticBinding.getCorePrivilegeStatus;
+export const setCorePrivileges = diagnosticBinding.setCorePrivileges;
+export const inspectApplication = diagnosticBinding.inspectApplication;
+export const scanWindowsApplications =
+  diagnosticBinding.scanWindowsApplications;
+export const getCurrentUserSid = diagnosticBinding.getCurrentUserSid;
+export const isRunningAsAdmin = diagnosticBinding.isRunningAsAdmin;
+export const ensureKokoroBoxCoreFirewall =
+  diagnosticBinding.ensureKokoroBoxCoreFirewall;
+export const listUwpLoopbackApps = diagnosticBinding.listUwpLoopbackApps;
+export const setUwpLoopbackExemption =
+  diagnosticBinding.setUwpLoopbackExemption;
+export const ServiceIdentity = diagnosticBinding.ServiceIdentity;
+export const openServiceIdentity = diagnosticBinding.openServiceIdentity;
+export const deleteServiceIdentity = diagnosticBinding.deleteServiceIdentity;
+
+export const getSystemProxyDiagnostics = diagnosticBinding.getSystemProxyDiagnostics;
+export const setSystemProxy = diagnosticBinding.setSystemProxy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "KokoroBox native bridge",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,7 @@
   "license": "GPL-3.0-only",
   "files": [
     "index.js",
+    "diagnostics.js",
     "index.d.ts",
     "README.md"
   ],
@@ -32,6 +33,7 @@
     ]
   },
   "scripts": {
+    "test:logs": "node --test tests/diagnostics.test.mjs",
     "build": "napi build --platform --release --strip --no-js --dts napi.generated.d.ts",
     "build:debug": "napi build --platform --no-js --dts napi.generated.d.ts",
     "create-npm-dirs": "napi create-npm-dirs",
@@ -48,11 +50,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "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"
+    "kokorobox-native-win32-x64-msvc": "0.16.3",
+    "kokorobox-native-win32-arm64-msvc": "0.16.3",
+    "kokorobox-native-darwin-x64": "0.16.3",
+    "kokorobox-native-darwin-arm64": "0.16.3",
+    "kokorobox-native-linux-x64-gnu": "0.16.3",
+    "kokorobox-native-linux-arm64-gnu": "0.16.3"
   }
 }