kokorobox-native 0.16.1 → 0.16.2

package/README.md

@@ -29,6 +29,20 @@ 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`.
+
 ## Documentation
 
 - [JavaScript API guide](../docs/api.md)

package/diagnostics.js

@@ -0,0 +1,125 @@
+// 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",
+]);
+
+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 (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;

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,88 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokorobox-native",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "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.2",
+    "kokorobox-native-win32-arm64-msvc": "0.16.2",
+    "kokorobox-native-darwin-x64": "0.16.2",
+    "kokorobox-native-darwin-arm64": "0.16.2",
+    "kokorobox-native-linux-x64-gnu": "0.16.2",
+    "kokorobox-native-linux-arm64-gnu": "0.16.2"
   }
 }