feat: add macos-continue-if-no-devs-found config option

Add macOS equivalent of linux-continue-if-no-devs-found. When enabled,
kanata keeps running if no matching devices are found at startup and
automatically captures them when they connect, using driverkit's IOKit
notification system.

This also includes the fix from PR jtroo#1986 (don't fall back to grabbing
all devices when an include/exclude list has no matches).

Depends on psych3r/driverkit#17 for notification subscription support
for not-yet-connected devices.

Relates to jtroo#1479

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: malpern

docs/config.adoc

@@ -4880,6 +4880,29 @@ Use `kanata -l` or `kanata --list` to list the available keyboards.
   )
 )
 ----
+
+[[macos-only-macos-continue-if-no-devs-found]]
+=== macOS only: macos-continue-if-no-devs-found
+
+By default, kanata will exit with an error if no matching input devices are found.
+You can change this behaviour by setting `macos-continue-if-no-devs-found`.
+When enabled, kanata will keep running and automatically capture matching devices
+when they are connected.
+
+This is useful when running multiple kanata instances with
+`macos-dev-names-include`, where an external keyboard may not be connected
+at startup.
+
+.Example:
+[source]
+----
+(defcfg
+  macos-dev-names-include (
+    "External Keyboard"
+  )
+  macos-continue-if-no-devs-found yes
+)
+----
 [[windows-only-windows-altgr]]
 === Windows only: windows-altgr
 

parser/src/cfg/defcfg.rs

@@ -69,6 +69,7 @@ pub enum LinuxCfgOutputBusType {
 pub struct CfgMacosOptions {
     pub macos_dev_names_include: Option<Vec<String>>,
     pub macos_dev_names_exclude: Option<Vec<String>>,
+    pub macos_continue_if_no_devs_found: bool,
 }
 
 #[cfg(any(
@@ -679,6 +680,13 @@ pub fn parse_defcfg(expr: &[SExpr]) -> Result<CfgOptions> {
                             cfg.macos_opts.macos_dev_names_exclude = Some(dev_names);
                         }
                     }
+                    "macos-continue-if-no-devs-found" => {
+                        #[cfg(any(target_os = "macos", target_os = "unknown"))]
+                        {
+                            cfg.macos_opts.macos_continue_if_no_devs_found =
+                                parse_defcfg_val_bool(val, label)?
+                        }
+                    }
                     "tray-icon" => {
                         #[cfg(all(
                             any(target_os = "windows", target_os = "unknown"),

src/kanata/macos.rs

@@ -26,9 +26,10 @@ impl Kanata {
         let allow_hardware_repeat = k.allow_hardware_repeat;
         let include_names = k.include_names.clone();
         let exclude_names = k.exclude_names.clone();
+        let continue_if_no_devices = k.continue_if_no_devices;
         drop(k);
 
-        let mut kb = match KbdIn::new(include_names, exclude_names) {
+        let mut kb = match KbdIn::new(include_names, exclude_names, continue_if_no_devices) {
             Ok(kbd_in) => kbd_in,
             Err(e) => bail!("failed to open keyboard device(s): {}", e),
         };

src/kanata/mod.rs

@@ -223,6 +223,9 @@ pub struct Kanata {
     #[cfg(any(target_os = "linux", target_os = "android"))]
     /// Tracks the Linux user configuration to continue or abort if no devices are found.
     continue_if_no_devices: bool,
+    #[cfg(target_os = "macos")]
+    /// Tracks the macOS user configuration to continue or abort if no devices are found.
+    continue_if_no_devices: bool,
     #[cfg(any(target_os = "linux", target_os = "android", target_os = "macos"))]
     /// Tracks the Linux/Macos user configuration for device names (instead of paths) that should be
     /// included for interception and processing by kanata.
@@ -474,6 +477,8 @@ impl Kanata {
             include_names: cfg.options.macos_opts.macos_dev_names_include,
             #[cfg(target_os = "macos")]
             exclude_names: cfg.options.macos_opts.macos_dev_names_exclude,
+            #[cfg(target_os = "macos")]
+            continue_if_no_devices: cfg.options.macos_opts.macos_continue_if_no_devs_found,
             #[cfg(any(target_os = "linux", target_os = "android"))]
             kbd_in_paths: cfg.options.linux_opts.linux_dev,
             #[cfg(any(target_os = "linux", target_os = "android"))]
@@ -624,6 +629,8 @@ impl Kanata {
             include_names: cfg.options.macos_opts.macos_dev_names_include,
             #[cfg(target_os = "macos")]
             exclude_names: cfg.options.macos_opts.macos_dev_names_exclude,
+            #[cfg(target_os = "macos")]
+            continue_if_no_devices: cfg.options.macos_opts.macos_continue_if_no_devs_found,
             #[cfg(any(target_os = "linux", target_os = "android"))]
             kbd_in_paths: cfg.options.linux_opts.linux_dev,
             #[cfg(any(target_os = "linux", target_os = "android"))]

src/oskbd/macos.rs

@@ -50,6 +50,7 @@ impl From<InputEvent> for DKEvent {
             value: event.value,
             page: event.page,
             code: event.code,
+            device_hash: 0,
         }
     }
 }
@@ -70,6 +71,7 @@ impl KbdIn {
     pub fn new(
         include_names: Option<Vec<String>>,
         exclude_names: Option<Vec<String>>,
+        continue_if_no_devices: bool,
     ) -> Result<Self, anyhow::Error> {
         if !driver_activated() {
             return Err(anyhow!(
@@ -79,8 +81,9 @@ impl KbdIn {
 
         // Based on the definition of include and exclude names, they should never be used together.
         // Kanata config parser should probably enforce this.
+        let has_device_filter = include_names.is_some() || exclude_names.is_some();
         let device_names = if let Some(included_names) = include_names {
-            validate_and_register_devices(included_names)
+            validate_and_register_devices(included_names, continue_if_no_devices)
         } else if let Some(excluded_names) = exclude_names {
             // get all devices
             let kb_list = fetch_devices();
@@ -99,12 +102,22 @@ impl KbdIn {
                 .collect::<Vec<String>>();
 
             // register the remeining devices
-            validate_and_register_devices(devices_to_include)
+            validate_and_register_devices(devices_to_include, continue_if_no_devices)
         } else {
             vec![]
         };
 
-        if !device_names.is_empty() || register_device("") {
+        // When an include/exclude list is configured but no devices matched,
+        // do NOT fall back to registering all devices. Only use the catch-all
+        // register_device("") when no device filter was specified at all.
+        if !device_names.is_empty() || (!has_device_filter && register_device("")) {
+            if grab() {
+                Ok(Self { grabbed: true })
+            } else {
+                Err(anyhow!("grab failed"))
+            }
+        } else if continue_if_no_devices && has_device_filter {
+            log::warn!("no matching devices found; waiting for device to connect");
             if grab() {
                 Ok(Self { grabbed: true })
             } else {
@@ -123,6 +136,7 @@ impl KbdIn {
             value: 0,
             page: 0,
             code: 0,
+            device_hash: 0,
         };
 
         let got_event = wait_key(&mut event);
@@ -163,7 +177,10 @@ impl KbdIn {
     }
 }
 
-fn validate_and_register_devices(include_names: Vec<String>) -> Vec<String> {
+fn validate_and_register_devices(
+    include_names: Vec<String>,
+    continue_if_no_devices: bool,
+) -> Vec<String> {
     include_names
         .iter()
         .filter_map(|dev| {
@@ -179,12 +196,17 @@ fn validate_and_register_devices(include_names: Vec<String>) -> Vec<String> {
                 return None;
             }
 
-            match device_matches(dev) {
-                true => Some(dev.to_string()),
-                false => {
-                    log::warn!("'{dev}' doesn't match any connected device");
-                    None
-                }
+            if device_matches(dev) {
+                Some(dev.to_string())
+            } else if continue_if_no_devices {
+                // Device not connected, but register it anyway so driverkit
+                // can auto-capture it via IOKit notifications when it appears.
+                log::warn!("'{dev}' not connected; will capture when it appears");
+                register_device(dev);
+                None
+            } else {
+                log::warn!("'{dev}' doesn't match any connected device");
+                None
             }
         })
         .filter_map(|dev| {