hid-keymap 0.1.0 → 0.2.1

package/README.md

@@ -22,6 +22,8 @@ hid-keymap --map 0x01/0x97=key:escape
 hid-keymap --map 0x01/0x97=left_command+key:space
 ```
 
+Mapping mode launches a separate menu bar utility and returns to the shell. Open its keyboard icon to see the configured source-to-target mappings, current status, and controls to stop, restart, or quit. The `--monitor` Event Viewer remains in the terminal and prints raw HID usage/value events.
+
 Use `hid-keymap --list-targets` to list accepted target names. By default, it listens to all keyboard collections; add `--device VID/PID` to scope a monitor or mapping to one keyboard.
 
 ## Permissions and behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hid-keymap",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "macOS HID keyboard event viewer and key mapper",
   "bin": {
     "hid-keymap": "bin/hid-keymap.js"

package/src/hid-keymap.swift

@@ -1,11 +1,14 @@
 import ApplicationServices
+import AppKit
 import CoreGraphics
+import Darwin
 import Foundation
 import IOKit.hid
 import IOKit.hidsystem
 
 private let genericDesktopPage = 0x01
 private let keyboardUsage = 0x06
+private let appVersion = "0.2.1"
 
 private struct HIDCode: Hashable, CustomStringConvertible {
     let page: UInt32
@@ -183,6 +186,51 @@ private func parseInteger(_ raw: String) -> UInt32? {
     return UInt32(raw, radix: 10)
 }
 
+private func launchDetachedMapping(_ arguments: [String]) throws {
+    let executablePath = CommandLine.arguments[0]
+    let childArguments = [executablePath, "--_background_mapping"] + arguments
+    var cArguments = childArguments.map { strdup($0) }
+    guard cArguments.allSatisfy({ $0 != nil }) else {
+        cArguments.forEach { if let argument = $0 { free(argument) } }
+        throw CLIError("Could not prepare background process arguments")
+    }
+    cArguments.append(nil)
+    defer { cArguments.forEach { if let argument = $0 { free(argument) } } }
+
+    var fileActions: posix_spawn_file_actions_t?
+    var spawnAttributes: posix_spawnattr_t?
+    guard posix_spawn_file_actions_init(&fileActions) == 0 else {
+        throw CLIError("Could not initialize background process file actions")
+    }
+    defer { posix_spawn_file_actions_destroy(&fileActions) }
+    guard posix_spawnattr_init(&spawnAttributes) == 0 else {
+        throw CLIError("Could not initialize background process attributes")
+    }
+    defer { posix_spawnattr_destroy(&spawnAttributes) }
+
+    let redirectInput = posix_spawn_file_actions_addopen(&fileActions, STDIN_FILENO, "/dev/null", O_RDONLY, 0)
+    let redirectOutput = posix_spawn_file_actions_addopen(&fileActions, STDOUT_FILENO, "/dev/null", O_WRONLY, 0)
+    let redirectError = posix_spawn_file_actions_addopen(&fileActions, STDERR_FILENO, "/dev/null", O_WRONLY, 0)
+    guard redirectInput == 0, redirectOutput == 0, redirectError == 0 else {
+        throw CLIError("Could not detach background process from the terminal")
+    }
+    guard posix_spawnattr_setflags(&spawnAttributes, Int16(POSIX_SPAWN_SETSID)) == 0 else {
+        throw CLIError("Could not create a detached session for the mapping process")
+    }
+
+    var childPID: pid_t = 0
+    let result = executablePath.withCString { path in
+        cArguments.withUnsafeBufferPointer { buffer in
+            posix_spawn(&childPID, path, &fileActions, &spawnAttributes, buffer.baseAddress, environ)
+        }
+    }
+    guard result == 0 else {
+        throw CLIError("Could not start the menu bar mapping process (system error \(result))")
+    }
+    print("Started hid-keymap mapping process (pid \(childPID)). Open the keyboard icon in the menu bar.")
+    fflush(stdout)
+}
+
 private struct CLIError: Error, CustomStringConvertible {
     let message: String
     init(_ message: String) { self.message = message }
@@ -198,6 +246,10 @@ private func parseArguments(_ arguments: [String]) throws -> CLIOptions {
         printUsage()
         exit(EXIT_SUCCESS)
     }
+    if arguments == ["--version"] || arguments == ["-V"] {
+        print("hid-keymap \(appVersion)")
+        exit(EXIT_SUCCESS)
+    }
     if arguments == ["--list-targets"] {
         printTargets()
         exit(EXIT_SUCCESS)
@@ -246,7 +298,7 @@ private func parseArguments(_ arguments: [String]) throws -> CLIOptions {
 
 private func printUsage() {
     print("""
-    hid-keymap — HID Event Viewer / keyboard mapper
+    hid-keymap \(appVersion) — HID Event Viewer / keyboard mapper
 
     Usage:
       hid-keymap --monitor [--device VID/PID]
@@ -255,6 +307,8 @@ private func printUsage() {
           Map one or more non-keyboard HID state usages to held keys or modifiers.
       hid-keymap --list-targets
           List supported target key names.
+      hid-keymap --version
+          Print the installed version.
 
     Example:
       hid-keymap --monitor
@@ -305,6 +359,8 @@ private final class HIDMapper {
     private var activeTargets = Set<KeyTarget>()
     private var connectedDevices = Set<String>()
     private let formatter = ISO8601DateFormatter()
+    var onStatusChange: ((String) -> Void)?
+    private(set) var status = "Not started"
 
     init(options: CLIOptions) {
         eventViewer = options.monitor
@@ -356,9 +412,7 @@ private final class HIDMapper {
             print("Listening for HID changes from \(scope). Press Ctrl-C to stop.")
             print("Timestamp                      Device                                  Usage page   Usage        Value")
         } else {
-            for (source, target) in mappings.sorted(by: { $0.key.description < $1.key.description }) {
-                print("Mapping \(source) → \(target). Press Ctrl-C to stop.")
-            }
+            setStatus("Ready · \(mappings.count) mapping\(mappings.count == 1 ? "" : "s")")
         }
         fflush(stdout)
     }
@@ -386,6 +440,9 @@ private final class HIDMapper {
         guard changed else { return }
 
         updateTargets()
+        if !eventViewer, let target = mappings[code] {
+            setStatus(isDown ? "Pressed · \(target)" : "Ready · \(mappings.count) mapping\(mappings.count == 1 ? "" : "s")")
+        }
     }
 
     func setConnected(_ rawDevice: IOHIDDevice, connected: Bool) {
@@ -399,6 +456,7 @@ private final class HIDMapper {
             if eventViewer { print("[Disconnected] \(device.label)") }
             activeSources = activeSources.filter { $0.deviceID != device.id }
             updateTargets()
+            if !eventViewer { setStatus("Keyboard disconnected · waiting for input") }
         }
     }
 
@@ -429,6 +487,7 @@ private final class HIDMapper {
             IOHIDManagerUnscheduleFromRunLoop(manager, CFRunLoopGetMain(), CFRunLoopMode.defaultMode.rawValue)
         }
         manager = nil
+        if !eventViewer { setStatus("Stopped") }
     }
 
     private func releaseAllTargets() {
@@ -456,19 +515,160 @@ private final class HIDMapper {
             fputs("Could not create event for \(target)\n", stderr)
             return
         }
-        event.flags = target.modifiers.reduce(flags) { $0.union($1.flag) }
+        // A modifier's key-up event must report that the released modifier is
+        // no longer down. Chord key-up events still carry their chord flags;
+        // modifier-only releases rely on the remaining active targets' flags.
+        event.flags = down || target.modifierOnly == nil
+            ? target.modifiers.reduce(flags) { $0.union($1.flag) }
+            : flags
         event.post(tap: .cghidEventTap)
     }
+
+    func reportError(_ error: Error) {
+        setStatus(String(describing: error))
+    }
+
+    private func setStatus(_ newStatus: String) {
+        status = newStatus
+        onStatusChange?(newStatus)
+    }
+}
+
+private final class MappingMenuApp: NSObject, NSApplicationDelegate {
+    private let mapper: HIDMapper
+    private let mappings: [HIDMapping]
+    private let deviceFilter: DeviceFilter?
+    private var statusItem: NSStatusItem?
+    private var statusMenuItem: NSMenuItem?
+    private var interruptSource: DispatchSourceSignal?
+    private var terminateSource: DispatchSourceSignal?
+
+    init(options: CLIOptions) {
+        mapper = HIDMapper(options: options)
+        mappings = options.mappings ?? []
+        deviceFilter = options.deviceFilter
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        buildMenu()
+        mapper.onStatusChange = { [weak self] status in
+            self?.statusMenuItem?.title = status
+            self?.statusItem?.button?.toolTip = "hid-keymap · \(status)"
+        }
+        installSignalHandlers()
+        startMapping()
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        mapper.stop()
+    }
+
+    @objc private func stopMapping() {
+        mapper.stop()
+    }
+
+    @objc private func restartMapping() {
+        mapper.stop()
+        startMapping()
+    }
+
+    @objc private func quit() {
+        mapper.stop()
+        NSApp.terminate(nil)
+    }
+
+    private func startMapping() {
+        do {
+            try mapper.start()
+        } catch {
+            mapper.reportError(error)
+        }
+    }
+
+    private func buildMenu() {
+        let item = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+        if let image = NSImage(systemSymbolName: "keyboard", accessibilityDescription: "hid-keymap")?
+            .withSymbolConfiguration(NSImage.SymbolConfiguration(pointSize: 18, weight: .medium)) {
+            image.isTemplate = true
+            item.button?.image = image
+        } else {
+            item.button?.title = "⌨"
+        }
+        item.button?.toolTip = "hid-keymap"
+
+        let menu = NSMenu()
+        let status = NSMenuItem(title: mapper.status, action: nil, keyEquivalent: "")
+        status.isEnabled = false
+        menu.addItem(status)
+        statusMenuItem = status
+        menu.addItem(.separator())
+
+        for mapping in mappings.sorted(by: { $0.source.description < $1.source.description }) {
+            let line = NSMenuItem(title: "\(mapping.source) → \(mapping.target)", action: nil, keyEquivalent: "")
+            line.isEnabled = false
+            menu.addItem(line)
+        }
+        if let deviceFilter {
+            let scope = NSMenuItem(title: String(format: "Device · 0x%04x/0x%04x", deviceFilter.vendorID, deviceFilter.productID), action: nil, keyEquivalent: "")
+            scope.isEnabled = false
+            menu.addItem(scope)
+        } else {
+            let scope = NSMenuItem(title: "Device · all keyboards", action: nil, keyEquivalent: "")
+            scope.isEnabled = false
+            menu.addItem(scope)
+        }
+        menu.addItem(.separator())
+
+        let stopItem = NSMenuItem(title: "Stop Mapping", action: #selector(stopMapping), keyEquivalent: "")
+        stopItem.target = self
+        menu.addItem(stopItem)
+        let restartItem = NSMenuItem(title: "Restart Mapping", action: #selector(restartMapping), keyEquivalent: "")
+        restartItem.target = self
+        menu.addItem(restartItem)
+        menu.addItem(.separator())
+        let quitItem = NSMenuItem(title: "Quit hid-keymap", action: #selector(quit), keyEquivalent: "q")
+        quitItem.target = self
+        menu.addItem(quitItem)
+        item.menu = menu
+        statusItem = item
+    }
+
+    private func installSignalHandlers() {
+        signal(SIGINT, SIG_IGN)
+        let interrupt = DispatchSource.makeSignalSource(signal: SIGINT, queue: .main)
+        interrupt.setEventHandler { [weak self] in self?.quit() }
+        interrupt.resume()
+        interruptSource = interrupt
+
+        signal(SIGTERM, SIG_IGN)
+        let terminate = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main)
+        terminate.setEventHandler { [weak self] in self?.quit() }
+        terminate.resume()
+        terminateSource = terminate
+    }
 }
 
 @main
 enum FnHIDMapMain {
     static func main() {
         do {
-            let options = try parseArguments(Array(CommandLine.arguments.dropFirst()))
-            let mapper = HIDMapper(options: options)
-            try mapper.start()
-            mapper.run()
+            let arguments = Array(CommandLine.arguments.dropFirst())
+            let isBackgroundMapping = arguments.first == "--_background_mapping"
+            let userArguments = isBackgroundMapping ? Array(arguments.dropFirst()) : arguments
+            let options = try parseArguments(userArguments)
+            if options.monitor {
+                let mapper = HIDMapper(options: options)
+                try mapper.start()
+                mapper.run()
+            } else if !isBackgroundMapping {
+                try launchDetachedMapping(userArguments)
+            } else {
+                let app = NSApplication.shared
+                let delegate = MappingMenuApp(options: options)
+                app.delegate = delegate
+                app.run()
+            }
         } catch {
             fputs("hid-keymap: \(error)\nUse --help for usage.\n", stderr)
             exit(EXIT_FAILURE)