twokey 1.0.12 → 1.0.14

package/README.md

@@ -12,9 +12,15 @@ The core idea matches the video workflow:
 ## What Works Now
 
 - Global hold hotkey on X11 for voice capture.
+- Wayland compositor detection (GNOME/KDE/Sway/Hyprland) with compositor-specific runtime capability messaging.
+- Wayland automation integration paths:
+  - text insertion via `wtype` or `ydotool`
+  - selected-text read via `wtype` + `wl-paste` when available
 - Double-tap hotkey to cycle modes.
 - Single-tap hotkey to open file-context picker.
 - Voice-triggered toolchains for multi-step desktop actions.
+- Visual toolchain editor in settings with dry-run and manual execution controls.
+- Toolchain safety guardrails (dangerous shell pattern blocking).
 - Four modes:
   - Conversation
   - Edit Text
@@ -43,6 +49,14 @@ The core idea matches the video workflow:
 - Tray icon and settings window.
 - GitHub release check from settings.
 - In-app AppImage update download and launch.
+- Optional in-app background update download to staged AppImage file.
+- Local Whisper auto-setup on first use:
+  - managed `ffmpeg` in `~/.local/share/twokey/bin/`
+  - managed Whisper venv in `~/.local/share/twokey/whisper-venv/`
+- Local Whisper tuning in settings:
+  - model selection (`tiny` .. `large-v3`)
+  - beam size tuning (speed vs quality)
+- Visible install/save status in settings (including install spinner).
 
 ## Current Video Parity
 
@@ -58,14 +72,22 @@ Implemented from video behavior:
 
 Still not fully equivalent to the video vision:
 
-- Toolchains are implemented, but no visual workflow builder exists yet.
+- Toolchains have a visual settings editor; richer action templates and safety controls are still pending.
 - Wayland still has compositor-specific limits for global hold hotkeys and full automation.
-- Update install is available for AppImage, but no signed rollback-capable updater pipeline yet.
+- Update install is AppImage-first with channel-aware checks (`stable`/`beta`/`dev`), checksum validation and local rollback fallback.
+
+Current workflow action catalog:
+
+- `open_url`
+- `open_app`
+- `shell` (with safety blocking for known dangerous patterns)
+- `wait_ms`
+- `check_command`
 
 ## Install
 
 ```bash
-npm install twokey
+npm install -g twokey
 ```
 
 Run:
@@ -78,6 +100,7 @@ Default behavior:
 
 - starts native desktop app in background
 - if no native binary is installed, tries to download latest AppImage release
+- prepares runtime dependencies in user space (best effort, no system package mutation)
 
 Useful options:
 
@@ -86,8 +109,16 @@ twokey --help
 twokey --cli
 twokey --once "Erklaere X11 vs Wayland kurz"
 twokey --desktop
+twokey --prepare-runtime
+twokey --prepare-runtime-only
 ```
 
+Updater behavior:
+
+- Uses update channel from settings (`stable`, `beta`, `dev`).
+- Verifies AppImage checksum when a `.sha256` asset is available.
+- Restores previous local AppImage if updated binary cannot be started.
+
 ## Development
 
 Install dependencies:
@@ -114,6 +145,14 @@ npm run build
 cd src-tauri && cargo check
 ```
 
+Runtime smoke tests:
+
+```bash
+cargo test --manifest-path src-tauri/Cargo.toml runtime_e2e -- --nocapture
+TWOKEY_E2E_SESSION=x11 cargo test --manifest-path src-tauri/Cargo.toml runtime_e2e -- --nocapture
+TWOKEY_E2E_SESSION=wayland cargo test --manifest-path src-tauri/Cargo.toml runtime_e2e -- --nocapture
+```
+
 ## Hotkey Behavior
 
 Default hotkey can be changed in settings. Examples:
@@ -146,6 +185,8 @@ Configured in settings (`sttProvider`):
 
 `external-command` needs `TWOKEY_STT_COMMAND` with `{audio}` placeholder.
 
+For `local-whisper`, TwoKey attempts runtime setup in user space and checks required binaries before transcription.
+
 Example:
 
 ```bash
@@ -171,6 +212,11 @@ Optional runtime tools:
 - PDF extraction: `poppler-utils` (`pdftotext`)
 - TTS backends: `spd-say` or `espeak-ng`/`espeak`
 
+Notes:
+
+- `ffmpeg` is auto-provisioned to `~/.local/share/twokey/bin/ffmpeg` if missing.
+- Local Whisper CLI is auto-provisioned to `~/.local/share/twokey/whisper-venv/bin/whisper` if missing.
+
 ## Data Paths
 
 - Config: `~/.config/twokey-ai/`
@@ -178,11 +224,17 @@ Optional runtime tools:
 - Cache: `~/.cache/twokey-ai/`
 - History DB: `~/.local/share/twokey-ai/history.db`
 - Toolchains: `~/.config/twokey-ai/toolchains.json`
+- Managed runtime bin: `~/.local/share/twokey/bin/`
+- Managed Whisper venv: `~/.local/share/twokey/whisper-venv/`
 
 ## Repo
 
 https://github.com/meinzeug/twokey
 
+## Additional Docs
+
+- Wayland matrix: `docs/WAYLAND_COMPATIBILITY_MATRIX.md`
+
 ## License
 
 MIT

package/bin/postinstall.js

@@ -56,6 +56,10 @@ if (isRoot && sudoUser && sudoUser !== "root") {
   delegated.on("error", () => process.exit(0));
   delegated.on("close", () => process.exit(0));
 } else {
+  if (isRoot) {
+    ensureSystemTtsBackend();
+  }
+
   const runtimePrep = spawn(process.execPath, [cliPath, "--prepare-runtime-only", "--quiet"], {
     stdio: "ignore",
     shell: false,
@@ -103,3 +107,34 @@ function isDesktopRunningForUser(username) {
   const out = spawnSync("pgrep", ["-u", username, "-f", "twokey-ai(\\.AppImage)?"], { encoding: "utf8" });
   return out.status === 0;
 }
+
+function ensureSystemTtsBackend() {
+  if (hasAnyTtsBackend()) {
+    return;
+  }
+
+  if (!commandExists("apt-get")) {
+    return;
+  }
+
+  try {
+    const result = spawnSync("apt-get", ["install", "-y", "espeak-ng"], {
+      stdio: "ignore",
+      shell: false,
+    });
+    if (result.status !== 0) {
+      return;
+    }
+  } catch {
+    // best effort
+  }
+}
+
+function hasAnyTtsBackend() {
+  return commandExists("spd-say") || commandExists("espeak-ng") || commandExists("espeak");
+}
+
+function commandExists(name) {
+  const out = spawnSync("sh", ["-c", `command -v ${name} >/dev/null 2>&1`], { encoding: "utf8" });
+  return out.status === 0;
+}

package/bin/twokey.js

@@ -375,6 +375,7 @@ async function ensureRuntimeDependencies() {
   await fs.promises.mkdir(APPIMAGE_DIR, { recursive: true });
   await ensureManagedFfmpeg();
   await ensureManagedWhisperCli();
+  await ensureManagedTtsBackend();
 }
 
 async function ensureManagedFfmpeg() {
@@ -426,6 +427,24 @@ async function ensureManagedWhisperCli() {
   }
 }
 
+async function ensureManagedTtsBackend() {
+  if (await commandExists("spd-say") || await commandExists("espeak-ng") || await commandExists("espeak")) {
+    return;
+  }
+
+  if (!isRoot()) {
+    return;
+  }
+
+  if (await commandExists("apt-get")) {
+    try {
+      await runCommand("apt-get", ["install", "-y", "espeak-ng"]);
+    } catch {
+      // best effort only
+    }
+  }
+}
+
 async function commandExists(name) {
   return new Promise((resolve) => {
     const child = spawn("sh", ["-c", `command -v ${name} >/dev/null 2>&1`], {
@@ -437,6 +456,10 @@ async function commandExists(name) {
   });
 }
 
+function isRoot() {
+  return typeof process.getuid === "function" && process.getuid() === 0;
+}
+
 async function runCommand(program, commandArgs) {
   return new Promise((resolve, reject) => {
     const child = spawn(program, commandArgs, {
@@ -471,6 +494,11 @@ function withManagedBinPath(baseEnv) {
     parts.unshift(APPIMAGE_DIR);
   }
   env.PATH = parts.join(":");
+  // Remove variables that interfere with Python virtual environments.
+  // An inherited PYTHONHOME or PYTHONPATH causes the venv interpreter to look
+  // for the standard library (including "encodings") in the wrong location.
+  delete env.PYTHONHOME;
+  delete env.PYTHONPATH;
   return env;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twokey",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Linux-first desktop AI assistant built with Tauri, React, and TypeScript.",
   "license": "MIT",
   "repository": {