claude-kvm-native 1.0.0

package/lib/hid.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { charToKeysym, namedKeyToKeysym } from '../utils/keysym.js';
+
+/**
+ * HID Controller — KVM-style input via VNC.
+ *
+ * Tracks cursor position. Uses direct teleport for move.
+ * Smooth interpolation only for drag operations.
+ * Click operations use the current tracked position.
+ */
+
+// VNC button masks
+const BUTTON = {
+  LEFT: 1,
+  MIDDLE: 2,
+  RIGHT: 4,
+  SCROLL_UP: 8,
+  SCROLL_DOWN: 16,
+  SCROLL_LEFT: 32,
+  SCROLL_RIGHT: 64,
+};
+
+export class HIDController {
+  /**
+   * @param {import('./types.js').ClaudeKVMConfig} config
+   * @param {import('./vnc.js').VNCClient} vncClient
+   */
+  constructor(config, vncClient) {
+    this.vnc = vncClient;
+    this.clickHoldMs = config.hid.click_hold_ms;
+    this.keyHoldMs = config.hid.key_hold_ms;
+    this.typingDelay = config.hid.typing_delay_ms;
+    this.scrollEventsPerStep = config.hid.scroll_events_per_step ?? 5;
+
+    /** @type {number} Current cursor X (native resolution) */
+    this.cursorX = 0;
+    /** @type {number} Current cursor Y (native resolution) */
+    this.cursorY = 0;
+  }
+
+  // ── Cursor Position ──────────────────────────────────────
+
+  /**
+   * Get current cursor position in native coordinates.
+   * @returns {import('./types.js').CursorPosition}
+   */
+  getCursorPosition() {
+    return { x: this.cursorX, y: this.cursorY };
+  }
+
+  // ── Mouse: Move ──────────────────────────────────────────
+
+  /**
+   * Teleport cursor to target position (single pointer event).
+   * @param {number} x - Target X (native resolution)
+   * @param {number} y - Target Y (native resolution)
+   */
+  async mouseMove(x, y) {
+    this.vnc.pointerEvent(x, y, 0);
+    this.cursorX = x;
+    this.cursorY = y;
+  }
+
+  // ── Mouse: Click (at current position) ───────────────────
+
+  /**
+   * Click at current cursor position.
+   * @param {'left' | 'middle' | 'right'} [button='left']
+   */
+  async mouseClick(button = 'left') {
+    const mask = button === 'right' ? BUTTON.RIGHT :
+                 button === 'middle' ? BUTTON.MIDDLE : BUTTON.LEFT;
+
+    this.vnc.pointerEvent(this.cursorX, this.cursorY, mask);
+    await sleep(this.clickHoldMs);
+    this.vnc.pointerEvent(this.cursorX, this.cursorY, 0);
+  }
+
+  /** Double-click at current cursor position. */
+  async mouseDoubleClick() {
+    await this.mouseClick('left');
+    await sleep(50);
+    await this.mouseClick('left');
+  }
+
+  // ── Mouse: Drag ──────────────────────────────────────────
+
+  /**
+   * Drag from current position to target (smooth).
+   * @param {number} endX - Target X (native resolution)
+   * @param {number} endY - Target Y (native resolution)
+   */
+  async mouseDrag(endX, endY) {
+    // Press at current position
+    this.vnc.pointerEvent(this.cursorX, this.cursorY, BUTTON.LEFT);
+    await sleep(100);
+
+    // Smooth drag to target
+    const steps = Math.max(5, Math.ceil(
+      Math.hypot(endX - this.cursorX, endY - this.cursorY) / 30
+    ));
+    const startX = this.cursorX;
+    const startY = this.cursorY;
+
+    for (let i = 1; i <= steps; i++) {
+      const t = i / steps;
+      const ix = Math.round(startX + (endX - startX) * t);
+      const iy = Math.round(startY + (endY - startY) * t);
+      this.vnc.pointerEvent(ix, iy, BUTTON.LEFT);
+      await sleep(12);
+    }
+
+    // Release
+    this.vnc.pointerEvent(endX, endY, 0);
+    this.cursorX = endX;
+    this.cursorY = endY;
+  }
+
+  // ── Mouse: Scroll ────────────────────────────────────────
+
+  /**
+   * Scroll at current cursor position.
+   * @param {'up' | 'down' | 'left' | 'right'} direction
+   * @param {number} [amount=3]
+   */
+  async scroll(direction, amount = 3) {
+    const buttonMask = direction === 'up' ? BUTTON.SCROLL_UP :
+                       direction === 'down' ? BUTTON.SCROLL_DOWN :
+                       direction === 'left' ? BUTTON.SCROLL_LEFT :
+                       BUTTON.SCROLL_RIGHT;
+
+    for (let i = 0; i < amount; i++) {
+      for (let j = 0; j < this.scrollEventsPerStep; j++) {
+        this.vnc.pointerEvent(this.cursorX, this.cursorY, buttonMask);
+        await sleep(10);
+        this.vnc.pointerEvent(this.cursorX, this.cursorY, 0);
+        await sleep(10);
+      }
+      await sleep(30);
+    }
+  }
+
+  // ── Keyboard ─────────────────────────────────────────────
+
+  /** @param {string} key */
+  async keyPress(key) {
+    const keysym = namedKeyToKeysym(key);
+    if (!keysym) {
+      console.warn(`HID: unknown key "${key}"`);
+      return;
+    }
+    this.vnc.keyEvent(keysym, true);
+    await sleep(this.keyHoldMs);
+    this.vnc.keyEvent(keysym, false);
+  }
+
+  /** @param {string} combo - Keys separated by '+' */
+  async keyCombo(combo) {
+    const keys = combo.split('+').map(k => k.trim().toLowerCase());
+    /** @type {number[]} */
+    const keysyms = [];
+
+    for (const k of keys) {
+      const ks = namedKeyToKeysym(k);
+      if (ks) {
+        keysyms.push(ks);
+      } else {
+        const charKs = charToKeysym(k);
+        if (charKs) keysyms.push(charKs.keysym);
+        else { console.warn(`HID: unknown key in combo "${k}"`); return; }
+      }
+    }
+
+    for (const ks of keysyms) {
+      this.vnc.keyEvent(ks, true);
+      await sleep(50);
+    }
+    await sleep(80);
+    for (let i = keysyms.length - 1; i >= 0; i--) {
+      this.vnc.keyEvent(keysyms[i], false);
+      await sleep(50);
+    }
+  }
+
+  /** @param {string} text */
+  async typeText(text) {
+    for (const ch of text) {
+      const mapping = charToKeysym(ch);
+      if (!mapping) {
+        console.warn(`HID: unmapped char '${ch}' (${ch.charCodeAt(0)})`);
+        continue;
+      }
+
+      const { keysym, shift } = mapping;
+      const delay = this.typingDelay.min +
+        Math.random() * (this.typingDelay.max - this.typingDelay.min);
+
+      if (shift) {
+        this.vnc.keyEvent(0xFFE1, true);
+        await sleep(20);
+      }
+
+      this.vnc.keyEvent(keysym, true);
+      await sleep(this.keyHoldMs);
+      this.vnc.keyEvent(keysym, false);
+
+      if (shift) {
+        await sleep(20);
+        this.vnc.keyEvent(0xFFE1, false);
+      }
+
+      await sleep(delay);
+    }
+  }
+
+  /**
+   * Paste text via clipboard, or typeText fallback on macOS.
+   * Apple VNC doesn't bridge ClientCutText to the system pasteboard.
+   * @param {string} text
+   */
+  async pasteText(text) {
+    if (this.vnc.isMacOS) {
+      await this.typeText(text);
+      return;
+    }
+    this.vnc.setClipboard(text);
+    await sleep(100);
+    await this.keyCombo('ctrl+v');
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/lib/ssh.js

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { Client } from 'ssh2';
+import { readFileSync } from 'node:fs';
+
+function dbg(label, ...args) {
+  const ts = new Date().toISOString().slice(11, 23);
+  console.error(`[SSH ${ts}] ${label}`, ...args);
+}
+
+export class SSHClient {
+  /**
+   * @param {import('./types.js').SSHConnectionConfig} config
+   */
+  constructor(config) {
+    this.host = config.host;
+    this.port = config.port || 22;
+    this.username = config.username;
+    this.password = config.password || null;
+    this.privateKeyPath = config.privateKeyPath || null;
+
+    /** @type {import('ssh2').Client | null} */
+    this._client = null;
+    /** @type {boolean} */
+    this.connected = false;
+    /** @type {boolean} */
+    this.connecting = false;
+    /** @type {number} */
+    this.commandCount = 0;
+
+    dbg('INIT', `target=${this.host}:${this.port} user=${this.username} auth=${this.password ? 'password' : this.privateKeyPath ? 'key' : 'none'}`);
+  }
+
+  /**
+   * Connect to the SSH server. Resolves when ready.
+   * @returns {Promise<void>}
+   */
+  connect() {
+    if (this.connected) return Promise.resolve();
+    if (this.connecting) return this._connectPromise;
+
+    this.connecting = true;
+    this._connectPromise = new Promise((resolve, reject) => {
+      this._client = new Client();
+
+      const connectConfig = {
+        host: this.host,
+        port: this.port,
+        username: this.username,
+        readyTimeout: 10000,
+      };
+
+      if (this.privateKeyPath) {
+        try {
+          connectConfig.privateKey = readFileSync(this.privateKeyPath);
+          dbg('AUTH', `using key: ${this.privateKeyPath}`);
+        } catch (err) {
+          this.connecting = false;
+          reject(new Error(`Failed to read SSH key: ${err.message}`));
+          return;
+        }
+      } else if (this.password) {
+        connectConfig.password = this.password;
+        dbg('AUTH', 'using password');
+      }
+
+      this._client.on('ready', () => {
+        dbg('READY', `connected to ${this.host}:${this.port}`);
+        this.connected = true;
+        this.connecting = false;
+        resolve();
+      });
+
+      this._client.on('error', (err) => {
+        dbg('ERROR', err.message);
+        if (this.connecting) {
+          this.connecting = false;
+          reject(new Error(`SSH connection failed: ${err.message}`));
+        }
+      });
+
+      this._client.on('close', () => {
+        dbg('CLOSE', 'connection closed');
+        this.connected = false;
+        this.connecting = false;
+        this._client = null;
+      });
+
+      dbg('CONNECT', `opening SSH to ${this.host}:${this.port}...`);
+      this._client.connect(connectConfig);
+    });
+
+    return this._connectPromise;
+  }
+
+  /**
+   * Execute a command over SSH.
+   * @param {string} command
+   * @param {number} [timeoutMs=30000]
+   * @returns {Promise<{stdout: string, stderr: string, code: number}>}
+   */
+  async exec(command, timeoutMs = 30000) {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    this.commandCount++;
+    dbg('EXEC', `[#${this.commandCount}] ${command}`);
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`SSH command timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this._client.exec(command, (err, stream) => {
+        if (err) {
+          clearTimeout(timer);
+          reject(new Error(`SSH exec error: ${err.message}`));
+          return;
+        }
+
+        let stdout = '';
+        let stderr = '';
+
+        stream.on('data', (data) => { stdout += data.toString(); });
+        stream.stderr.on('data', (data) => { stderr += data.toString(); });
+
+        stream.on('close', (code) => {
+          clearTimeout(timer);
+          dbg('EXEC', `[#${this.commandCount}] exit=${code} stdout=${stdout.length}B stderr=${stderr.length}B`);
+          resolve({ stdout, stderr, code: code ?? 0 });
+        });
+      });
+    });
+  }
+
+  /**
+   * Disconnect from the SSH server.
+   */
+  disconnect() {
+    dbg('DISCONNECT', 'closing connection');
+    if (this._client) {
+      this._client.end();
+      this._client = null;
+    }
+    this.connected = false;
+    this.connecting = false;
+  }
+}

package/lib/types.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2025 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+/**
+ * @typedef {object} VNCConnectionConfig
+ * @property {string} host
+ * @property {number} port
+ * @property {'auto' | 'none'} auth
+ * @property {string} [username]
+ * @property {string} [password]
+ */
+
+/**
+ * @typedef {object} TypingDelayConfig
+ * @property {number} min
+ * @property {number} max
+ */
+
+/**
+ * @typedef {object} HIDConfig
+ * @property {number} click_hold_ms
+ * @property {number} key_hold_ms
+ * @property {TypingDelayConfig} typing_delay_ms
+ * @property {number} scroll_events_per_step
+ */
+
+/**
+ * @typedef {object} CaptureConfig
+ */
+
+/**
+ * @typedef {object} DiffConfig
+ * @property {number} pixel_threshold
+ */
+
+/**
+ * @typedef {object} DisplayConfig
+ * @property {number} max_dimension
+ */
+
+/**
+ * @typedef {object} VNCTimeoutConfig
+ * @property {number} connect_timeout_ms
+ * @property {number} screenshot_timeout_ms
+ */
+
+/**
+ * @typedef {object} ClaudeKVMConfig
+ * @property {DisplayConfig} [display]
+ * @property {HIDConfig} hid
+ * @property {CaptureConfig} capture
+ * @property {DiffConfig} diff
+ * @property {VNCTimeoutConfig} [vnc_timeouts]
+ */
+
+/**
+ * @typedef {object} PixelFormat
+ * @property {number} bitsPerPixel
+ * @property {number} depth
+ * @property {number} bigEndian
+ * @property {number} trueColour
+ * @property {number} redMax
+ * @property {number} greenMax
+ * @property {number} blueMax
+ * @property {number} redShift
+ * @property {number} greenShift
+ * @property {number} blueShift
+ */
+
+/**
+ * @typedef {object} VNCServerInfo
+ * @property {number} width
+ * @property {number} height
+ * @property {string} name
+ */
+
+/**
+ * @typedef {object} ScreenshotResult
+ * @property {Buffer} buffer
+ * @property {string} base64
+ * @property {number} width
+ * @property {number} height
+ */
+
+
+/**
+ * @typedef {object} QuickDiffResult
+ * @property {boolean} changeDetected
+ */
+
+/**
+ * @typedef {object} ScaledDisplay
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * @typedef {object} ToolExecResult
+ * @property {string} text
+ * @property {string} [imageBase64]
+ * @property {boolean} [done]
+ * @property {'success' | 'failed'} [status]
+ */
+
+/**
+ * @typedef {object} KeysymMapping
+ * @property {number} keysym
+ * @property {boolean} shift
+ */
+
+/**
+ * @typedef {object} CursorPosition
+ * @property {number} x
+ * @property {number} y
+ */
+
+/**
+ * @typedef {object} SSHConnectionConfig
+ * @property {string} host
+ * @property {number} [port]
+ * @property {string} username
+ * @property {string} [password]
+ * @property {string} [privateKeyPath]
+ */
+
+export {};