keyspy 1.0.4 → 1.0.6

package/README.md

@@ -1,19 +1,43 @@
-# KeySpy 🕵️
+# keyspy 🕵️
 
 > A powerful, cross-platform keyboard and mouse event listener for Node.js
 
-KeySpy is a modern, lightweight library that provides global keyboard and mouse event monitoring across Windows, macOS, and Linux. Unlike other solutions, KeySpy uses pre-compiled native binaries and a multi-process architecture for maximum stability and compatibility.
+keyspy is a modern, lightweight library that provides global keyboard and mouse event monitoring across Windows, macOS, and Linux. Unlike other solutions, keyspy uses pre-compiled native binaries and a multi-process architecture for maximum stability and compatibility.
+
+## 🤔 Why keyspy?
+
+Choosing the right keyboard listener for your Node.js project can be challenging. Here's how keyspy compares to other popular solutions:
+
+| Feature | Electron globalShortcut | IOHook | **keyspy** |
+|---------|-------------------------|---------|------------|
+| **Zero compilation** | ❌ Electron required | ❌ node-gyp required | ✅ Pre-compiled binaries |
+| **Package size** | 🟡 Large (Electron) | 🟡 Medium | ✅ Small (on-demand download) |
+| **System shortcuts** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Event blocking** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Cross-platform** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **TypeScript** | ✅ Built-in | 🟡 Community types | ✅ Built-in |
+| **Stability** | ✅ Very stable | 🟡 Can crash Node.js | ✅ Multi-process isolation |
+
+### 🎯 **keyspy Advantages**
+
+- **🚀 Zero Setup**: Pre-compiled binaries downloaded automatically, no compilation required
+- **📦 Smaller Package**: Binaries downloaded on-demand (not bundled), reducing package size by ~90%
+- **📱 Universal macOS**: ARM64 + x86_64 universal binaries for all Apple Silicon and Intel Macs
+- **🔄 Modern Stack**: TypeScript, automated testing, and modern development tools
+- **🏗️ Automated Releases**: GitHub Actions handle cross-platform compilation and publishing
+- **🛡️ Stable Architecture**: Multi-process design prevents Node.js crashes
+- **⚡ High Performance**: Optimized native implementations for each platform
+
+> **📚 Project Origin**: keyspy is a modernized version of [node-global-key-listener](https://github.com/LaunchMenu/node-global-key-listener), rebuilt with modern tooling and enhanced features.
 
 ## ✨ Features
 
-- 🌍 **Cross-platform**: Works on Windows, macOS, and Linux (X11)
-- 🚀 **Zero compilation**: Pre-compiled binaries downloaded automatically, no node-gyp required
-- 🔒 **System-level capture**: Can intercept system shortcuts like Ctrl+Alt+Delete, Cmd+Space
+- 🌍 **Cross-platform**: Windows, macOS, and Linux (X11) support
+- 🔒 **System-level capture**: Intercept any key combination, including OS shortcuts
 - 🎯 **Event blocking**: Prevent captured events from reaching other applications
-- 📦 **TypeScript ready**: Full TypeScript support with comprehensive type definitions
-- 🏗️ **Modern architecture**: Multi-process design for enhanced stability
+- 📦 **TypeScript ready**: Full type definitions included
+- 🛡️ **Stable architecture**: Multi-process design prevents crashes
 - ⚡ **High performance**: Optimized native implementations for each platform
-- 📥 **Smart installation**: Automatically downloads platform-specific binaries from GitHub Releases
 
 ## 🔧 Platform Support
 
@@ -106,89 +130,69 @@ keyspy.kill(); // Removes all listeners and stops the key server
 ```bash
 npm install keyspy
 # or
-pnpm add keyspy
-# or
 yarn add keyspy
 ```
 
-**What happens during installation:**
-1. 📦 Downloads the main package (TypeScript code)
-2. 🔍 Detects your platform (Windows/macOS/Linux) and architecture
-3. 📥 Automatically downloads the appropriate pre-compiled binary from GitHub Releases
-4. ✅ Ready to use immediately!
+The package automatically detects your platform and downloads the appropriate pre-compiled binary during installation. No compilation required!
 
-## 🤔 Why KeySpy?
 
-Choosing the right keyboard listener for your Node.js project can be challenging. Here's how KeySpy compares to other popular solutions:
-
-| Feature | Electron globalShortcut | IOHook | **KeySpy** |
-|---------|------------------------|--------|------------|
-| **Setup Complexity** | Simple | Complex (node-gyp) | **Simple** |
-| **System Shortcuts** | ❌ Limited | ✅ Full | **✅ Full** |
-| **Event Blocking** | ❌ No | ✅ Yes | **✅ Yes** |
-| **Node.js Compatibility** | ❌ Electron only | ⚠️ Version dependent | **✅ All versions** |
-| **Compilation Required** | ❌ No | ❌ Yes | **✅ No** |
-| **Arbitrary Key Support** | ❌ Limited | ⚠️ Limited | **✅ Full** |
-| **Process Architecture** | In-process | In-process | **Multi-process** |
-
-### 🎯 **KeySpy Advantages**
-
-- **🔧 Zero Setup**: Pre-compiled binaries work out of the box
-- **🌐 Universal**: Compatible with all Node.js versions (14+)
-- **🔒 System-Level**: Capture any key combination, including OS shortcuts
-- **🛡️ Stable**: Multi-process architecture prevents crashes
-- **📝 TypeScript**: Full type definitions included
-- **🎮 Flexible**: Listen to individual keys or complex combinations
-
-### ⚠️ **Considerations**
-
-- **Permissions**: macOS requires Accessibility permissions
-- **Antivirus**: Some antivirus software may flag the native binaries
-- **Performance**: Small overhead due to inter-process communication
 
 ## 🛠️ Development
 
-### Quick Development Setup
-
 ```bash
 # Clone and setup
 git clone https://github.com/teomyth/keyspy.git
 cd keyspy
-pnpm install
+npm install
+
+# Build native binary for development
+npm run build:native
 
-# Development workflow
-pnpm dev          # Watch mode compilation
-pnpm build        # Production build
-pnpm test         # Run all tests
-pnpm test:manual  # Interactive testing
+# Development commands
+npm run dev          # TypeScript watch mode
+npm run build        # Production build
+npm test             # Run all tests
+npm run test:manual  # Interactive testing
 ```
 
 ### Building Native Binaries
 
-KeySpy includes pre-compiled binaries, but you can rebuild them if needed:
+For development, you can rebuild the native binaries:
 
 ```bash
-# Platform-specific builds
-pnpm build:win    # Windows (requires MinGW)
-pnpm build:swift  # macOS (requires Xcode)
-pnpm build:x11    # Linux (requires X11 dev libraries)
+# Auto-detect your platform
+npm run build:native
+
+# Force specific platform
+npm run build:native -- --platform darwin  # macOS (requires Xcode)
+npm run build:native -- --platform linux   # Linux (requires X11 dev libraries)
+npm run build:native -- --platform win32   # Windows (requires MinGW)
+
+# Show detailed build output
+npm run build:native -- --verbose
 ```
 
 ### Code Quality
 
 ```bash
-pnpm lint         # Check code quality with Biome
-pnpm lint:fix     # Auto-fix issues
-pnpm format       # Format code
-pnpm clean        # Remove build artifacts
+npm run lint         # Check code quality with Biome
+npm run lint:fix     # Auto-fix issues
+npm run format       # Format code
+npm run clean        # Remove build artifacts
+
+# Release management
+npm run release:patch    # Bump patch version (1.0.0 → 1.0.1)
+npm run release:minor    # Bump minor version (1.0.0 → 1.1.0)
+npm run release:major    # Bump major version (1.0.0 → 2.0.0)
+npm run release:dry      # Preview release without publishing
 ```
 
 ### Testing
 
 ```bash
-pnpm test:unit        # Unit tests
-pnpm test:integration # Integration tests
-pnpm test:manual      # Manual interactive testing
+npm run test:unit        # Unit tests
+npm run test:integration # Integration tests
+npm run test:manual      # Manual interactive testing
 ```
 
 ## 📋 API Reference
@@ -236,36 +240,17 @@ interface IGlobalKeyEvent {
 
 ## 🔧 Troubleshooting
 
-### Binary Download Issues
-
-If the automatic binary download fails during installation:
-
-```bash
-# Option 1: Manual download from GitHub Releases
-# Visit: https://github.com/teomyth/keyspy/releases
-# Download the appropriate file for your platform
-
-# Option 2: Build from source
-npm run build:swift  # macOS
-npm run build:x11    # Linux
-npm run build:win    # Windows
-
-# Option 3: Skip download in CI environments
-export KEYSPY_SKIP_DOWNLOAD=true
-npm install keyspy
-```
+### Common Issues
 
-### Platform Support
+1. **Binary download fails**: Visit [GitHub Releases](https://github.com/teomyth/keyspy/releases) to download manually, or build from source with `npm run build:native`
+2. **Permission denied**: Make sure the binary has execute permissions (`chmod +x bin/*`)
+3. **CI environments**: Set `KEYSPY_SKIP_DOWNLOAD=true` to skip binary download
 
-- **macOS**: ARM64 (Apple Silicon) and x64 (Intel) - Universal binary
-- **Linux**: x64 only, requires X11
-- **Windows**: x64 only
+### Platform Requirements
 
-### Common Issues
-
-1. **"Binary not found"**: Run the appropriate build command for your platform
-2. **Permission denied**: Make sure the binary has execute permissions (`chmod +x`)
-3. **Network issues**: Check your internet connection and GitHub access
+- **macOS**: macOS 10.14+, supports both Intel and Apple Silicon
+- **Linux**: X11 display server, x64 architecture
+- **Windows**: Windows 10+, x64 architecture
 
 ## 🤝 Contributing
 
@@ -280,8 +265,3 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- Original concept inspired by [LaunchMenu](https://github.com/LaunchMenu/LaunchMenu)
-- Built with modern tooling: TypeScript, Biome, Jest, and Turbo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyspy",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A cross-platform global keyboard and mouse listener for Node.js",
   "types": "build/index.d.ts",
   "main": "build/index.js",
@@ -13,28 +13,29 @@
   "engines": {
     "node": ">=14.0.0"
   },
-  "packageManager": "pnpm@8.0.0",
   "scripts": {
     "dev": "tsc --watch",
     "build": "tsc",
     "postinstall": "node scripts/download-binaries.js",
-    "build:swift": "scripts/compile-swift.sh",
-    "build:mac": "mkdir -p bin && swiftc src/bin/MacKeyServer/main.swift -o bin/MacKeyServer",
-    "build:win": ".\\scripts\\compile-win.bat",
-    "build:x11": "scripts/compile-x11.sh",
+    "build:native": "node scripts/build-native.js",
     "test": "jest",
     "test:unit": "jest tests/unit",
     "test:integration": "jest tests/integration",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
     "test:manual": "npx ts-node examples/manual-test.ts",
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "format": "biome format --write .",
     "format:check": "biome format .",
-    "clean": "rm -rf build dist coverage test-reports .turbo",
+    "clean": "rm -rf build dist coverage test-results .turbo",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run test",
     "release": "release-it",
-    "release:dry": "release-it --dry-run"
+    "release:dry": "release-it --dry-run",
+    "release:patch": "release-it patch",
+    "release:minor": "release-it minor",
+    "release:major": "release-it major"
   },
   "repository": {
     "type": "git",

package/scripts/download-binaries.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
-const fs = require('node:fs');
-const path = require('node:path');
-const https = require('node:https');
-const { execSync } = require('node:child_process');
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+const { execSync } = require("node:child_process");
 
-const packageJson = require('../package.json');
+const packageJson = require("../package.json");
 const version = packageJson.version;
 
 // Platform detection
@@ -14,16 +14,16 @@ const arch = process.arch;
 
 // Binary mapping
 const binaryMap = {
-  'darwin': {
-    'arm64': { file: 'MacKeyServer', archive: 'keyspy-darwin-arm64.tar.gz' },
-    'x64': { file: 'MacKeyServer', archive: 'keyspy-darwin-x64.tar.gz' }
+  darwin: {
+    arm64: { file: "MacKeyServer", archive: "keyspy-darwin-arm64.tar.gz" },
+    x64: { file: "MacKeyServer", archive: "keyspy-darwin-x64.tar.gz" },
   },
-  'linux': {
-    'x64': { file: 'X11KeyServer', archive: 'keyspy-linux-x64.tar.gz' }
+  linux: {
+    x64: { file: "X11KeyServer", archive: "keyspy-linux-x64.tar.gz" },
+  },
+  win32: {
+    x64: { file: "WinKeyServer.exe", archive: "keyspy-win32-x64.tar.gz" },
   },
-  'win32': {
-    'x64': { file: 'WinKeyServer.exe', archive: 'keyspy-win32-x64.tar.gz' }
-  }
 };
 
 function log(message) {
@@ -39,56 +39,58 @@ function getPlatformInfo() {
   if (!platformInfo) {
     throw new Error(`Unsupported platform: ${platform}`);
   }
-  
+
   const archInfo = platformInfo[arch];
   if (!archInfo) {
     throw new Error(`Unsupported architecture: ${arch} on ${platform}`);
   }
-  
+
   return archInfo;
 }
 
 function downloadFile(url, dest) {
   return new Promise((resolve, reject) => {
     log(`Downloading ${url}`);
-    
+
     const file = fs.createWriteStream(dest);
-    
-    https.get(url, (response) => {
-      if (response.statusCode === 302 || response.statusCode === 301) {
-        // Handle redirect
-        return downloadFile(response.headers.location, dest).then(resolve).catch(reject);
-      }
-      
-      if (response.statusCode !== 200) {
-        reject(new Error(`Download failed with status ${response.statusCode}`));
-        return;
-      }
-      
-      response.pipe(file);
-      
-      file.on('finish', () => {
-        file.close();
-        resolve();
-      });
-      
-      file.on('error', (err) => {
-        fs.unlink(dest, () => {
-          // Ignore unlink errors - file cleanup is best effort
-        }); // Delete partial file
-        reject(err);
-      });
-    }).on('error', reject);
+
+    https
+      .get(url, (response) => {
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          // Handle redirect
+          return downloadFile(response.headers.location, dest).then(resolve).catch(reject);
+        }
+
+        if (response.statusCode !== 200) {
+          reject(new Error(`Download failed with status ${response.statusCode}`));
+          return;
+        }
+
+        response.pipe(file);
+
+        file.on("finish", () => {
+          file.close();
+          resolve();
+        });
+
+        file.on("error", (err) => {
+          fs.unlink(dest, () => {
+            // Ignore unlink errors - file cleanup is best effort
+          }); // Delete partial file
+          reject(err);
+        });
+      })
+      .on("error", reject);
   });
 }
 
 function extractTarGz(archivePath, extractDir) {
   try {
     // Try using tar command
-    execSync(`tar -xzf "${archivePath}" -C "${extractDir}"`, { stdio: 'inherit' });
+    execSync(`tar -xzf "${archivePath}" -C "${extractDir}"`, { stdio: "inherit" });
     return true;
   } catch (_err) {
-    log('tar command failed, trying alternative extraction...');
+    log("tar command failed, trying alternative extraction...");
     return false;
   }
 }
@@ -96,39 +98,39 @@ function extractTarGz(archivePath, extractDir) {
 async function downloadAndExtract() {
   try {
     const { file: binaryFile, archive } = getPlatformInfo();
-    
+
     // Create bin directory
-    const binDir = path.join(__dirname, '..', 'bin');
+    const binDir = path.join(__dirname, "..", "bin");
     if (!fs.existsSync(binDir)) {
       fs.mkdirSync(binDir, { recursive: true });
     }
-    
+
     const binaryPath = path.join(binDir, binaryFile);
-    
+
     // Check if binary already exists
     if (fs.existsSync(binaryPath)) {
       log(`Binary already exists: ${binaryPath}`);
       return;
     }
-    
+
     // Download URL
     const downloadUrl = `https://github.com/teomyth/keyspy/releases/download/v${version}/${archive}`;
     const archivePath = path.join(binDir, archive);
-    
+
     log(`Platform: ${platform}-${arch}`);
     log(`Binary: ${binaryFile}`);
-    
+
     try {
       // Download archive
       await downloadFile(downloadUrl, archivePath);
       log(`Downloaded: ${archive}`);
-      
+
       // Extract archive
       if (extractTarGz(archivePath, binDir)) {
         log(`Extracted: ${archive}`);
-        
+
         // Make binary executable (Unix systems)
-        if (platform !== 'win32') {
+        if (platform !== "win32") {
           try {
             fs.chmodSync(binaryPath, 0o755);
             log(`Made executable: ${binaryFile}`);
@@ -136,43 +138,41 @@ async function downloadAndExtract() {
             log(`Warning: Could not make binary executable: ${err.message}`);
           }
         }
-        
+
         // Clean up archive
         fs.unlinkSync(archivePath);
         log(`Cleaned up: ${archive}`);
-        
+
         log(`✅ Successfully installed binary: ${binaryFile}`);
       } else {
-        throw new Error('Failed to extract archive');
+        throw new Error("Failed to extract archive");
       }
-      
     } catch (downloadErr) {
       error(`Failed to download binary: ${downloadErr.message}`);
-      log('');
-      log('📝 Manual installation options:');
-      log('1. Download from: https://github.com/teomyth/keyspy/releases');
-      log('2. Build from source:');
-      log('   - macOS: npm run build:swift');
-      log('   - Linux: npm run build:x11');
-      log('   - Windows: npm run build:win');
-      log('');
-      log('⚠️  KeySpy will not work without the platform-specific binary.');
-      
+      log("");
+      log("📝 Manual installation options:");
+      log("1. Download from: https://github.com/teomyth/keyspy/releases");
+      log("2. Build from source:");
+      log("   - macOS: npm run build:swift");
+      log("   - Linux: npm run build:x11");
+      log("   - Windows: npm run build:win");
+      log("");
+      log("⚠️  keyspy will not work without the platform-specific binary.");
+
       // Don't fail the installation, just warn
       process.exit(0);
     }
-    
   } catch (err) {
     error(err.message);
-    log('');
-    log('📋 Supported platforms:');
-    log('- macOS (ARM64, x64)');
-    log('- Linux (x64)'); 
-    log('- Windows (x64)');
-    log('');
-    log('If your platform should be supported, please report this issue:');
-    log('https://github.com/teomyth/keyspy/issues');
-    
+    log("");
+    log("📋 Supported platforms:");
+    log("- macOS (ARM64, x64)");
+    log("- Linux (x64)");
+    log("- Windows (x64)");
+    log("");
+    log("If your platform should be supported, please report this issue:");
+    log("https://github.com/teomyth/keyspy/issues");
+
     // Don't fail the installation for unsupported platforms
     process.exit(0);
   }
@@ -180,7 +180,7 @@ async function downloadAndExtract() {
 
 // Skip download in CI environments or if explicitly disabled
 if (process.env.CI || process.env.KEYSPY_SKIP_DOWNLOAD) {
-  log('Skipping binary download (CI environment or explicitly disabled)');
+  log("Skipping binary download (CI environment or explicitly disabled)");
   process.exit(0);
 }