flying-lobster 0.1.0

package/PRD.md

@@ -0,0 +1,76 @@
+# Flying Lobster 🦞 — PRD v1
+
+## What
+Lightweight, always-on-top desktop chat window for talking to OpenClaw bot gateway instances. One hotkey away, anywhere on your computer, even over fullscreen apps.
+
+## Tech Stack
+- **Electron** (cross-platform: Mac, Windows, Linux)
+- **electron-store** for persistent config (JSON on disk)
+- **BrowserWindow/WebView** embedding OpenClaw web UI (chat only)
+
+## Core Features (MVP)
+
+### 1. Global Hotkey
+- Default: `Cmd+Shift+L` (Mac) / `Ctrl+Shift+L` (Win)
+- User-customizable in settings
+- Toggles window show/hide
+
+### 2. Always-on-Top Window
+- Floats above ALL windows including fullscreen apps
+- Small footprint (~400x600, resizable)
+- Remembers position/size across restarts
+- Hide: hotkey, Esc, or click outside
+- Show: hotkey or tray icon click
+
+### 3. System Tray
+- Tray icon (🦞 or lobster icon)
+- Click to toggle window
+- Right-click menu: show, settings, quit
+
+### 4. Gateway Management
+- Add/edit/delete gateway configs (name + URL)
+- Switch between gateways via dropdown in app
+- Connection status indicator (green/red dot)
+- Persisted via electron-store
+
+### 5. Chat-Only UI
+- Loads OpenClaw gateway web UI in webview
+- CSS injected to hide header, sidebar, nav — only chat visible
+- Auto-loads active gateway on startup
+
+### 6. Settings
+- Gateway list management
+- Hotkey customization
+- Window behavior preferences
+
+## Config Schema (electron-store)
+```json
+{
+  "gateways": [
+    { "id": "uuid", "name": "Rooty", "url": "http://localhost:19002" }
+  ],
+  "activeGateway": "uuid",
+  "hotkey": "CommandOrControl+Shift+L",
+  "windowBounds": { "x": 100, "y": 100, "width": 400, "height": 600 }
+}
+```
+
+## Architecture
+```
+System Tray 🦞
+    │
+Electron Main Process
+├── Global hotkey listener (globalShortcut)
+├── Window manager (show/hide/position)
+├── Config store (electron-store)
+└── BrowserWindow
+    ├── Gateway selector bar (top)
+    └── WebView → OpenClaw UI (CSS-injected, chat only)
+```
+
+## Out of Scope (v2+)
+- Native chat UI (replace webview)
+- Notifications/badges
+- File drag & drop
+- Multi-window
+- Auto-discovery of local gateways

package/bin/cli.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const APP_NAME = 'Flying Lobster.app';
+const INSTALL_PATH = '/Applications';
+
+function log(msg) {
+  console.log(`🦞 ${msg}`);
+}
+
+function error(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+function runCommand(cmd, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { 
+      stdio: 'inherit',
+      shell: true,
+      ...options 
+    });
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Command failed with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
+function findBuiltApp(projectRoot) {
+  const distDir = path.join(projectRoot, 'dist');
+  
+  // Check possible build output directories in order of preference
+  const possibleDirs = [
+    'mac-universal',
+    'mac-arm64', 
+    'mac-x64',
+    'mac'
+  ];
+  
+  for (const dir of possibleDirs) {
+    const appPath = path.join(distDir, dir, APP_NAME);
+    if (fs.existsSync(appPath)) {
+      return appPath;
+    }
+  }
+  
+  return null;
+}
+
+async function install() {
+  const projectRoot = path.resolve(__dirname, '..');
+  const destPath = path.join(INSTALL_PATH, APP_NAME);
+
+  log('Building Flying Lobster...');
+  
+  // Install dependencies if needed
+  if (!fs.existsSync(path.join(projectRoot, 'node_modules'))) {
+    log('Installing dependencies...');
+    await runCommand('npm', ['install'], { cwd: projectRoot });
+  }
+
+  // Build the app (dir target is faster than DMG for install)
+  try {
+    await runCommand('npm', ['run', 'build:dir'], { cwd: projectRoot });
+  } catch (e) {
+    error('Build failed. Make sure you have the right permissions and dependencies.');
+  }
+
+  // Find the built app
+  const appPath = findBuiltApp(projectRoot);
+  if (!appPath) {
+    error('Built app not found. Build may have failed.');
+  }
+  
+  log(`Found built app at: ${path.basename(path.dirname(appPath))}`);
+
+  // Remove existing installation
+  if (fs.existsSync(destPath)) {
+    log('Removing existing installation...');
+    try {
+      execSync(`rm -rf "${destPath}"`);
+    } catch (e) {
+      error(`Failed to remove existing app. Try: sudo rm -rf "${destPath}"`);
+    }
+  }
+
+  // Copy to Applications
+  log('Installing to /Applications...');
+  try {
+    execSync(`cp -R "${appPath}" "${INSTALL_PATH}/"`);
+  } catch (e) {
+    error(`Failed to copy app. Try running with sudo or copy manually from:\n   ${appPath}`);
+  }
+
+  // Open the app
+  log('Installation complete! ✨');
+  log(`Installed to: ${destPath}`);
+  log('');
+  log('Starting Flying Lobster...');
+  
+  spawn('open', [destPath], { detached: true, stdio: 'ignore' }).unref();
+  
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('  🦞 Flying Lobster is now installed!');
+  console.log('');
+  console.log('  Quick tips:');
+  console.log('  • Press Cmd+Shift+L to toggle the chat window');
+  console.log('  • Click the 🦞 tray icon to show/hide');
+  console.log('  • Add your OpenClaw gateway in Settings');
+  console.log('  • Cmd+Shift+Left/Right to switch gateways');
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+}
+
+async function uninstall() {
+  const destPath = path.join(INSTALL_PATH, APP_NAME);
+  
+  if (!fs.existsSync(destPath)) {
+    log('Flying Lobster is not installed.');
+    return;
+  }
+
+  log('Uninstalling Flying Lobster...');
+  
+  // Quit the app if running
+  try {
+    execSync('osascript -e \'quit app "Flying Lobster"\' 2>/dev/null || true');
+  } catch (e) {
+    // Ignore errors
+  }
+
+  // Remove the app
+  try {
+    execSync(`rm -rf "${destPath}"`);
+    log('Successfully uninstalled Flying Lobster.');
+  } catch (e) {
+    error(`Failed to remove app. Try: sudo rm -rf "${destPath}"`);
+  }
+}
+
+function showHelp() {
+  console.log(`
+🦞 Flying Lobster CLI
+
+Usage:
+  flying-lobster <command>
+
+Commands:
+  install     Build and install Flying Lobster to /Applications
+  uninstall   Remove Flying Lobster from /Applications
+  help        Show this help message
+
+Examples:
+  npx flying-lobster install
+  flying-lobster uninstall
+`);
+}
+
+async function main() {
+  const command = process.argv[2];
+
+  if (os.platform() !== 'darwin') {
+    error('Flying Lobster CLI install is currently macOS only.');
+  }
+
+  switch (command) {
+    case 'install':
+      await install();
+      break;
+    case 'uninstall':
+      await uninstall();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      showHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "flying-lobster",
+  "version": "0.1.0",
+  "description": "Always-on-top chat window for OpenClaw gateways 🦞",
+  "author": "Rootlab.ai",
+  "license": "MIT",
+  "main": "src/main/index.js",
+  "bin": {
+    "flying-lobster": "./bin/cli.js"
+  },
+  "scripts": {
+    "dev": "electron .",
+    "start": "electron .",
+    "build": "electron-builder --mac",
+    "build:dir": "electron-builder --mac --dir",
+    "install-app": "node bin/cli.js install"
+  },
+  "devDependencies": {
+    "electron": "^33.0.0",
+    "electron-builder": "^25.0.0"
+  },
+  "dependencies": {
+    "electron-store": "^8.2.0",
+    "uuid": "^13.0.0"
+  },
+  "build": {
+    "appId": "ai.rootlab.flying-lobster",
+    "productName": "Flying Lobster",
+    "files": [
+      "src/**/*",
+      "assets/**/*"
+    ],
+    "mac": {
+      "category": "public.app-category.productivity",
+      "target": [
+        {
+          "target": "dmg",
+          "arch": ["universal"]
+        },
+        {
+          "target": "dir",
+          "arch": ["universal"]
+        }
+      ]
+    },
+    "dmg": {
+      "title": "Flying Lobster",
+      "contents": [
+        {
+          "x": 130,
+          "y": 220
+        },
+        {
+          "x": 410,
+          "y": 220,
+          "type": "link",
+          "path": "/Applications"
+        }
+      ]
+    }
+  }
+}

package/src/main/index.js

@@ -0,0 +1,358 @@
+const { app, BrowserWindow, globalShortcut, Tray, Menu, nativeImage, ipcMain, webContents, nativeTheme } = require('electron');
+const path = require('path');
+const store = require('./store');
+const { randomUUID } = require('crypto');
+
+// CSS to inject into OpenClaw webview to create chat-only view
+const OPENCLAW_CSS = `
+  :root, :host {
+    --shell-nav-width: 0px !important;
+    --shell-topbar-height: 0px !important;
+  }
+  .shell {
+    --shell-nav-width: 0px !important;
+    --shell-topbar-height: 0px !important;
+    grid-template-columns: 0px minmax(0,1fr) !important;
+    grid-template-rows: 0px 1fr !important;
+    grid-template-areas: "content" "content" !important;
+  }
+  .nav { display: none !important; }
+  .topbar { display: none !important; }
+  .content-header { display: none !important; }
+  .content {
+    padding: 0 4px !important;
+    gap: 0 !important;
+    grid-area: 1 / 1 / -1 / -1 !important;
+  }
+  .chat-controls { display: none !important; }
+  .chat-compose { padding: 8px 4px 4px !important; }
+  .chat-compose__row { gap: 6px !important; }
+  .chat-compose__field textarea {
+    min-height: 40px !important;
+    width: 100% !important;
+  }
+  .chat-compose__actions .btn:not(.primary) { display: none !important; }
+  .chat-compose__actions .btn .btn-kbd { display: none !important; }
+  .chat-compose__actions .btn { padding: 0 10px !important; }
+  .chat-group-messages { max-width: 100% !important; }
+  .chat-group { margin-right: 4px !important; margin-left: 4px !important; }
+`;
+
+const OPENCLAW_JS = `
+(function() {
+  const css = ${JSON.stringify(OPENCLAW_CSS)};
+  function injectCSS(root) {
+    if (!root || root.querySelector('[data-fl]')) return;
+    const s = document.createElement('style');
+    s.setAttribute('data-fl', '1');
+    s.textContent = css;
+    root.appendChild(s);
+  }
+  function inject() {
+    injectCSS(document.head);
+    document.documentElement.style.setProperty('--shell-nav-width', '0px', 'important');
+    document.documentElement.style.setProperty('--shell-topbar-height', '0px', 'important');
+    const app = document.querySelector('openclaw-app');
+    if (app && app.shadowRoot) {
+      injectCSS(app.shadowRoot);
+      const shell = app.shadowRoot.querySelector('.shell');
+      if (shell) shell.classList.add('shell--nav-collapsed');
+      app.shadowRoot.querySelectorAll('*').forEach(el => {
+        if (el.shadowRoot) injectCSS(el.shadowRoot);
+      });
+    }
+  }
+  inject();
+  let n = 0;
+  const iv = setInterval(() => { inject(); if (++n > 60) clearInterval(iv); }, 300);
+  const ob = new MutationObserver(inject);
+  if (document.body) ob.observe(document.body, { childList: true, subtree: true });
+  else document.addEventListener('DOMContentLoaded', () => ob.observe(document.body, { childList: true, subtree: true }));
+  setTimeout(() => { ob.disconnect(); clearInterval(iv); }, 30000);
+})();
+`;
+
+let mainWindow = null;
+let settingsWindow = null;
+let tray = null;
+
+// ── IPC Handlers ──────────────────────────────────────────────
+
+ipcMain.handle('get-gateways', () => store.get('gateways'));
+
+ipcMain.handle('add-gateway', (_e, { name, url, token }) => {
+  const gateways = store.get('gateways');
+  const gw = { id: randomUUID(), name, url, token: token || '' };
+  gateways.push(gw);
+  store.set('gateways', gateways);
+  // If first gateway, auto-activate
+  if (!store.get('activeGateway')) store.set('activeGateway', gw.id);
+  return gw;
+});
+
+ipcMain.handle('update-gateway', (_e, { id, name, url, token }) => {
+  const gateways = store.get('gateways').map(g =>
+    g.id === id ? { ...g, name, url, token: token || '' } : g
+  );
+  store.set('gateways', gateways);
+  return gateways;
+});
+
+ipcMain.handle('delete-gateway', (_e, id) => {
+  const gateways = store.get('gateways').filter(g => g.id !== id);
+  store.set('gateways', gateways);
+  if (store.get('activeGateway') === id) {
+    store.set('activeGateway', gateways.length ? gateways[0].id : null);
+  }
+  return gateways;
+});
+
+ipcMain.handle('get-active-gateway', () => store.get('activeGateway'));
+
+ipcMain.handle('set-active-gateway', (_e, id) => {
+  store.set('activeGateway', id);
+  return id;
+});
+
+ipcMain.handle('get-settings', () => ({
+  hotkey: store.get('hotkey'),
+}));
+
+ipcMain.handle('update-settings', (_e, settings) => {
+  if (settings.hotkey && settings.hotkey !== store.get('hotkey')) {
+    store.set('hotkey', settings.hotkey);
+    registerHotkey();
+  }
+  return { hotkey: store.get('hotkey') };
+});
+
+ipcMain.handle('open-settings', () => {
+  openSettings();
+});
+
+ipcMain.handle('ping-gateway', async (_e, url) => {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 3000);
+    const res = await fetch(url, { signal: ctrl.signal, method: 'HEAD' });
+    clearTimeout(t);
+    return res.ok || res.status < 500;
+  } catch {
+    return false;
+  }
+});
+
+// ── Theme Support ─────────────────────────────────────────────
+
+ipcMain.handle('get-theme', () => {
+  return nativeTheme.shouldUseDarkColors ? 'dark' : 'light';
+});
+
+// Notify all windows when theme changes
+nativeTheme.on('updated', () => {
+  const theme = nativeTheme.shouldUseDarkColors ? 'dark' : 'light';
+  if (mainWindow && !mainWindow.isDestroyed()) {
+    mainWindow.webContents.send('theme-changed', theme);
+  }
+  if (settingsWindow && !settingsWindow.isDestroyed()) {
+    settingsWindow.webContents.send('theme-changed', theme);
+  }
+});
+
+// ── Main Window ───────────────────────────────────────────────
+
+function createWindow() {
+  const bounds = store.get('windowBounds');
+
+  mainWindow = new BrowserWindow({
+    width: bounds.width || 400,
+    height: bounds.height || 600,
+    x: bounds.x,
+    y: bounds.y,
+    frame: false,
+    alwaysOnTop: true,
+    skipTaskbar: true,
+    resizable: true,
+    show: false,
+    transparent: false,
+    visibleOnAllWorkspaces: true,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      preload: path.join(__dirname, 'preload.js'),
+      webviewTag: true,
+    }
+  });
+
+  if (process.platform === 'darwin') {
+    mainWindow.setAlwaysOnTop(true, 'screen-saver');
+    mainWindow.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+  } else {
+    mainWindow.setAlwaysOnTop(true, 'screen-saver');
+  }
+
+  mainWindow.loadFile(path.join(__dirname, '..', 'renderer', 'index.html'));
+
+  // Inject CSS/JS into any webview that loads inside this window
+  mainWindow.webContents.on('did-attach-webview', (event, wvWebContents) => {
+    wvWebContents.on('dom-ready', () => {
+      wvWebContents.insertCSS(OPENCLAW_CSS).catch(e => console.error('Main insertCSS failed:', e));
+      wvWebContents.executeJavaScript(OPENCLAW_JS).catch(e => console.error('Main executeJS failed:', e));
+    });
+  });
+
+  const saveBounds = () => {
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      store.set('windowBounds', mainWindow.getBounds());
+    }
+  };
+  mainWindow.on('move', saveBounds);
+  mainWindow.on('resize', saveBounds);
+
+  mainWindow.on('blur', () => {
+    if (mainWindow && mainWindow.isVisible()) {
+      mainWindow.hide();
+    }
+  });
+
+  mainWindow.once('ready-to-show', () => {
+    mainWindow.show();
+  });
+
+  mainWindow.webContents.on('before-input-event', (event, input) => {
+    if (input.key === 'Escape') {
+      mainWindow.hide();
+    }
+  });
+
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+}
+
+// ── Settings Window ───────────────────────────────────────────
+
+function openSettings() {
+  if (settingsWindow && !settingsWindow.isDestroyed()) {
+    settingsWindow.focus();
+    return;
+  }
+
+  settingsWindow = new BrowserWindow({
+    width: 520,
+    height: 560,
+    resizable: false,
+    frame: false,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      preload: path.join(__dirname, 'preload-settings.js'),
+    }
+  });
+
+  settingsWindow.loadFile(path.join(__dirname, '..', 'renderer', 'settings.html'));
+
+  settingsWindow.on('closed', () => {
+    settingsWindow = null;
+    // Notify main window to refresh gateway list
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.webContents.send('gateways-updated');
+    }
+  });
+}
+
+// ── Agent Switching Shortcuts ─────────────────────────────────
+
+function cycleGateway(direction) {
+  const gateways = store.get('gateways');
+  if (gateways.length < 2) return; // Nothing to cycle
+  
+  const activeId = store.get('activeGateway');
+  const currentIndex = gateways.findIndex(g => g.id === activeId);
+  
+  let newIndex;
+  if (direction === 'next') {
+    newIndex = (currentIndex + 1) % gateways.length;
+  } else {
+    newIndex = (currentIndex - 1 + gateways.length) % gateways.length;
+  }
+  
+  const newGateway = gateways[newIndex];
+  store.set('activeGateway', newGateway.id);
+  
+  // Notify main window to switch gateway
+  if (mainWindow && !mainWindow.isDestroyed()) {
+    mainWindow.webContents.send('switch-gateway', newGateway.id);
+  }
+}
+
+// ── Toggle / Tray / Hotkey ────────────────────────────────────
+
+function toggleWindow() {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    createWindow();
+    return;
+  }
+  if (mainWindow.isVisible()) {
+    mainWindow.hide();
+  } else {
+    mainWindow.show();
+    mainWindow.focus();
+  }
+}
+
+function createTray() {
+  const icon = nativeImage.createFromDataURL(
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAARElEQVQ4T2P8z8BQz0BAwMBAAGBhYGD4T4whBgYGRmIMkG4Ao2uQGECyC0h2wWgYjIYBVcKAZC+QnJBIdgHJXiDZAABhvBAR2MfUzgAAAABJRU5ErkJggg=='
+  );
+
+  tray = new Tray(icon.resize({ width: 16, height: 16 }));
+  tray.setToolTip('Flying Lobster 🦞');
+
+  const contextMenu = Menu.buildFromTemplate([
+    { label: 'Show/Hide', click: toggleWindow },
+    { type: 'separator' },
+    { label: 'Settings', click: openSettings },
+    { type: 'separator' },
+    { label: 'Quit', click: () => app.quit() }
+  ]);
+
+  tray.setContextMenu(contextMenu);
+  tray.on('click', toggleWindow);
+}
+
+function registerHotkey() {
+  const hotkey = store.get('hotkey');
+  globalShortcut.unregisterAll();
+  
+  // Main toggle hotkey
+  const registered = globalShortcut.register(hotkey, toggleWindow);
+  if (!registered) {
+    console.error(`Failed to register hotkey: ${hotkey}`);
+  }
+  
+  // Agent switching shortcuts (Cmd+Shift+Right/Left)
+  const nextRegistered = globalShortcut.register('CommandOrControl+Shift+Right', () => cycleGateway('next'));
+  const prevRegistered = globalShortcut.register('CommandOrControl+Shift+Left', () => cycleGateway('prev'));
+  
+  if (!nextRegistered) console.error('Failed to register Cmd+Shift+Right');
+  if (!prevRegistered) console.error('Failed to register Cmd+Shift+Left');
+}
+
+if (process.platform === 'darwin') {
+  app.dock.hide();
+}
+
+app.whenReady().then(() => {
+  createWindow();
+  createTray();
+  registerHotkey();
+});
+
+app.on('will-quit', () => {
+  globalShortcut.unregisterAll();
+});
+
+app.on('window-all-closed', (e) => {
+  e.preventDefault?.();
+});

package/src/main/preload-settings.js

@@ -0,0 +1,13 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('api', {
+  getGateways: () => ipcRenderer.invoke('get-gateways'),
+  addGateway: (gateway) => ipcRenderer.invoke('add-gateway', gateway),
+  updateGateway: (gateway) => ipcRenderer.invoke('update-gateway', gateway),
+  deleteGateway: (id) => ipcRenderer.invoke('delete-gateway', id),
+  getSettings: () => ipcRenderer.invoke('get-settings'),
+  updateSettings: (settings) => ipcRenderer.invoke('update-settings', settings),
+  // Theme support
+  getTheme: () => ipcRenderer.invoke('get-theme'),
+  onThemeChanged: (cb) => ipcRenderer.on('theme-changed', (_event, theme) => cb(theme)),
+});