@mooncompany/uplink-chat 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moon Company LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# ⬡ Uplink
+
+[![npm version](https://img.shields.io/npm/v/uplink-chat)](https://www.npmjs.com/package/uplink-chat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+**Local-first AI chat with voice** — talk to any LLM from your own machine.
+
+<!-- TODO: Add hero screenshot showing Uplink chat interface -->
+
+Uplink is a self-hosted chat interface that runs as a lightweight Node.js server on your computer. Connect it to OpenAI, Anthropic, local models, or any OpenAI-compatible API. Add voice with free TTS/STT engines. Access from any device on your network.
+
+## Quick Start
+
+```bash
+npx uplink-chat
+```
+
+That's it. Open `http://localhost:3456` in your browser.
+
+## Install Globally
+
+```bash
+npm install -g uplink-chat
+uplink-chat start
+```
+
+## Features
+
+- **Any LLM** — OpenAI, Anthropic, Ollama, LM Studio, or any OpenAI-compatible endpoint
+- **Voice Chat** — Text-to-speech and speech-to-text with multiple engine options
+- **Agent Management** — Create, edit, delete, and route between OpenClaw agents directly from Uplink
+- **Local-First** — Runs on your machine. Your data stays on your machine.
+- **PWA** — Install as an app on desktop or mobile from your browser
+- **Themes** — 6 built-in themes (dark, light, OLED, and more)
+- **Mobile Ready** — Responsive UI, works great on phones via local network
+- **Satellites** — Connect multiple AI providers and switch between them
+- **File Uploads** — Attach images (JPEG, PNG, WebP, GIF), audio, video, and documents (PDF, DOCX, Excel) to chat messages
+- **Dashboard** — At-a-glance view of your conversations, agents, and provider status
+- **Split View** — View multiple conversations or panels side by side
+- **Keyboard Shortcuts** — Navigate and control the app without touching the mouse
+- **Encrypted Storage** — Optional password protection for your chat history
+- **Structured Logging** — LOG_LEVEL environment variable support (debug, info, warn, error, silent)
+
+## Voice Engines
+
+### Text-to-Speech (TTS)
+
+| Engine | Cost | Setup |
+|--------|------|-------|
+| Edge TTS | Free | None — works out of the box |
+| OpenAI TTS | Paid | API key required |
+| Coqui XTTS | Free | Local GPU server |
+| ElevenLabs | Paid (~$5/mo) | API key required |
+
+### Speech-to-Text (STT)
+
+| Engine | Cost | Setup |
+|--------|------|-------|
+| Browser STT | Free | None — built into browser |
+| Faster-Whisper | Free | Local server (pip or Docker) |
+| Groq Whisper | Free tier | API key required |
+| OpenAI Whisper | Paid (~$0.006/min) | API key required |
+
+## Logging
+
+Control verbosity with the `LOG_LEVEL` environment variable:
+
+```bash
+LOG_LEVEL=debug uplink-chat          # Verbose debugging output
+LOG_LEVEL=info uplink-chat           # Default (application events)
+LOG_LEVEL=warn uplink-chat           # Warnings and errors only
+LOG_LEVEL=error uplink-chat          # Errors only
+LOG_LEVEL=silent uplink-chat         # Suppress all logs
+```
+
+Default is `info`. Useful for troubleshooting or reducing console noise in production.
+
+## CLI
+
+```bash
+uplink-chat              # Start server (foreground)
+uplink-chat start        # Start server (foreground)
+uplink-chat start -d     # Start in background
+uplink-chat stop         # Stop background server
+uplink-chat status       # Check if running
+uplink-chat --port 8080  # Custom port
+uplink-chat --version    # Show version
+uplink-chat --help       # Show help
+```
+
+## Remote Access
+
+Uplink runs on `localhost` by default. To access from your phone or other devices:
+
+- **Same network** — Use your computer's local IP (e.g., `http://192.168.1.100:3456`)
+- **Anywhere** — Use [Tailscale](https://tailscale.com) for a private, encrypted connection (recommended)
+- **Advanced** — Cloudflare Tunnel or your own reverse proxy
+
+> **Note:** Microphone access (STT) requires HTTPS or localhost. Tailscale provides this automatically.
+
+## Configuration
+
+All settings are configured through the web UI — no config files to edit.
+
+On first launch, you'll be guided through:
+1. Naming your assistant
+2. Connecting your AI provider (API key + endpoint)
+3. Optional: voice setup, theme selection, password protection
+
+## Requirements
+
+- **Node.js 18+**
+- A browser (Chrome/Edge recommended for best voice support)
+- An AI provider API key (OpenAI, Anthropic, etc.) or a local model server
+
+## Connecting to OpenClaw
+
+Uplink can connect to [OpenClaw](https://openclaw.ai) as a gateway for AI providers. To use this:
+
+1. Enter your OpenClaw gateway URL and token in Uplink's settings (or during onboarding)
+2. **Enable the chat completions endpoint** in your OpenClaw config:
+
+```json
+{
+  "gateway": {
+    "http": {
+      "endpoints": {
+        "chatCompletions": {
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+> **⚠️ Important:** The `chatCompletions` endpoint is **disabled by default** in OpenClaw. Uplink sends all AI requests through `/v1/chat/completions` — if this endpoint isn't enabled, chat will silently fail or return errors. This is the #1 setup issue when connecting Uplink to OpenClaw.
+
+You can enable it via the OpenClaw CLI:
+```bash
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+```
+
+## Troubleshooting
+
+### sharp (Image Processing)
+
+`sharp` is a native dependency used for image processing. On some platforms it may require build tools (Python, C++ compiler) to install. If `npm install` fails due to sharp:
+
+```bash
+npm install --ignore-scripts
+npm rebuild sharp
+```
+
+On most systems, prebuilt binaries are downloaded automatically and no extra steps are needed.
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Chat sends but no AI response | `chatCompletions` endpoint disabled in OpenClaw | Enable it (see above) |
+| 401 errors in console | Auth token mismatch or missing | Check gateway token matches in both Uplink settings and OpenClaw config |
+| WebSocket 1006 error via Tailscale | Uplink/OpenClaw running in WSL while Tailscale runs on Windows | See WSL + Tailscale section below |
+| Mic not working on mobile | Not using HTTPS | Access via Tailscale or localhost (browsers require secure context for mic) |
+| Voice not working | TTS/STT engine not configured | Check voice settings — Edge TTS works out of the box with no setup |
+
+### WSL + Tailscale (Windows)
+
+If you run Uplink or OpenClaw inside **WSL** (Windows Subsystem for Linux) but Tailscale is installed on **Windows**, WebSocket connections over Tailscale will fail with a **1006 error**. This happens because WSL and Windows have separate network stacks — Tailscale traffic arrives at Windows, but can't reach the WSL instance.
+
+**Solutions (pick one):**
+
+1. **Install Tailscale inside WSL** (recommended) — Run `tailscale up` inside your Ubuntu/WSL instance so it gets its own Tailscale IP. Connect to that hostname instead.
+
+2. **Run Uplink on Windows directly** — Node.js works natively on Windows. This puts Uplink and Tailscale on the same network stack.
+
+3. **Port forward from Windows to WSL** — Forward traffic from your Windows Tailscale IP into WSL:
+   ```powershell
+   # Get your WSL IP (run inside WSL: hostname -I)
+   netsh interface portproxy add v4tov4 listenport=3456 listenaddress=0.0.0.0 connectport=3456 connectaddress=<WSL_IP>
+   ```
+   > ⚠️ WSL's IP can change on reboot, so you may need to update this.
+
+## License
+
+MIT — [Moon Company](https://moonco.pro)

package/bin/uplink.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * Uplink CLI
+ * Usage:
+ *   uplink-chat          → starts the server (default)
+ *   uplink-chat start    → starts the server
+ *   uplink-chat stop     → stops any running Uplink server
+ *   uplink-chat --port N → use custom port (default: 3456)
+ *   uplink-chat --help   → show help
+ */
+
+import { spawn, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, writeFileSync, readFileSync, unlinkSync } from 'fs';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..');
+const PID_FILE = join(ROOT, '.uplink.pid');
+const WATCHDOG_PID_FILE = join(ROOT, '.uplink-watchdog.pid');
+const WATCHDOG_STATE_FILE = join(ROOT, '.uplink-watchdog.json');
+
+const args = process.argv.slice(2);
+const command = args[0] || 'start';
+
+// Parse flags
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && args[i + 1]) {
+    flags.port = parseInt(args[i + 1], 10);
+    i++;
+  }
+  if (args[i] === '--host') {
+    flags.host = args[i + 1] || '0.0.0.0';
+    i++;
+  }
+  if (args[i] === '--help' || args[i] === '-h') {
+    flags.help = true;
+  }
+  if (args[i] === '--version' || args[i] === '-v') {
+    flags.version = true;
+  }
+  if (args[i] === '--detach' || args[i] === '-d') {
+    flags.detach = true;
+  }
+  if (args[i] === '--no-watchdog') {
+    flags.noWatchdog = true;
+  }
+}
+
+// Version
+if (flags.version) {
+  const require = createRequire(import.meta.url);
+  const pkg = require(join(ROOT, 'package.json'));
+  console.log(`uplink-chat v${pkg.version}`);
+  process.exit(0);
+}
+
+// Help
+if (flags.help) {
+  console.log(`
+  ⬡ Uplink — Local AI Chat
+
+  Usage:
+    uplink-chat [command] [options]
+
+  Commands:
+    start       Start the Uplink server (default)
+    stop        Stop a running Uplink server
+    status      Check if Uplink is running
+
+  Options:
+    --port N        Port to listen on (default: 3456)
+    --host H        Host to bind to (default: 0.0.0.0)
+    --detach, -d    Run in background (daemon mode)
+    --no-watchdog   Run without auto-restart watchdog
+    -v              Show version
+    -h              Show this help
+
+  Examples:
+    npx uplink-chat                  # Start on default port
+    npx uplink-chat --port 8080      # Start on port 8080
+    npx uplink-chat stop             # Stop the server
+  `);
+  process.exit(0);
+}
+
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPid() {
+  if (!existsSync(PID_FILE)) return null;
+  const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+  if (isNaN(pid) || !isRunning(pid)) {
+    // Stale pid file
+    try { unlinkSync(PID_FILE); } catch {}
+    return null;
+  }
+  return pid;
+}
+
+function getWatchdogPid() {
+  if (!existsSync(WATCHDOG_PID_FILE)) return null;
+  const pid = parseInt(readFileSync(WATCHDOG_PID_FILE, 'utf8').trim(), 10);
+  if (isNaN(pid) || !isRunning(pid)) {
+    try { unlinkSync(WATCHDOG_PID_FILE); } catch {}
+    return null;
+  }
+  return pid;
+}
+
+function getWatchdogState() {
+  if (!existsSync(WATCHDOG_STATE_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(WATCHDOG_STATE_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function formatUptime(ms) {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  if (days > 0) return `${days}d ${hours % 24}h ${minutes % 60}m`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+// ── STOP ──
+if (command === 'stop') {
+  // Try watchdog first (daemon mode), then direct PID
+  const watchdogPid = getWatchdogPid();
+  if (watchdogPid) {
+    try {
+      process.kill(watchdogPid, 'SIGTERM');
+      console.log(`⬡ Uplink watchdog stopped (PID ${watchdogPid}).`);
+      try { unlinkSync(WATCHDOG_PID_FILE); } catch {}
+      try { unlinkSync(PID_FILE); } catch {}
+    } catch (e) {
+      console.error(`⬡ Failed to stop Uplink watchdog (PID ${watchdogPid}):`, e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  const pid = getPid();
+  if (!pid) {
+    console.log('⬡ Uplink is not running.');
+    process.exit(0);
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    console.log(`⬡ Uplink stopped (PID ${pid}).`);
+    try { unlinkSync(PID_FILE); } catch {}
+  } catch (e) {
+    console.error(`⬡ Failed to stop Uplink (PID ${pid}):`, e.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── STATUS ──
+if (command === 'status') {
+  const watchdogPid = getWatchdogPid();
+  const state = getWatchdogState();
+  
+  if (watchdogPid && state) {
+    const uptime = formatUptime(Date.now() - state.startedAt);
+    console.log(`⬡ Uplink is running (watchdog mode)`);
+    console.log(`  Watchdog PID: ${watchdogPid}`);
+    if (state.serverPid) console.log(`  Server PID:   ${state.serverPid}`);
+    console.log(`  Uptime:       ${uptime}`);
+    console.log(`  Restarts:     ${state.restartCount || 0}`);
+    if (state.backoffMs > 1000) console.log(`  Backoff:      ${state.backoffMs}ms`);
+  } else {
+    const pid = getPid();
+    if (pid) {
+      console.log(`⬡ Uplink is running (PID ${pid}).`);
+    } else {
+      console.log('⬡ Uplink is not running.');
+    }
+  }
+  process.exit(0);
+}
+
+// ── START ──
+if (command === 'start' || !['stop', 'status'].includes(command)) {
+  // Check both watchdog and direct PID
+  const existingWatchdog = getWatchdogPid();
+  const existingPid = getPid();
+  if (existingWatchdog || existingPid) {
+    const pid = existingWatchdog || existingPid;
+    const mode = existingWatchdog ? 'watchdog' : 'direct';
+    console.log(`⬡ Uplink is already running (${mode}, PID ${pid}).`);
+    console.log(`  Stop it first: uplink-chat stop`);
+    process.exit(1);
+  }
+
+  const env = { ...process.env };
+  if (flags.port) env.PORT = String(flags.port);
+  if (flags.host) env.UPLINK_HOST = flags.host;
+
+  const serverPath = join(ROOT, 'server.js');
+
+  if (flags.detach) {
+    // Daemon mode — spawn watchdog (which spawns and monitors server)
+    const watchdogPath = join(ROOT, 'server', 'watchdog.js');
+    
+    // Pass extra env vars as JSON arg to watchdog
+    const extraEnv = {};
+    if (flags.port) extraEnv.PORT = String(flags.port);
+    if (flags.host) extraEnv.UPLINK_HOST = flags.host;
+    
+    const child = spawn(process.execPath, [watchdogPath, JSON.stringify(extraEnv)], {
+      cwd: ROOT,
+      env,
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    
+    const port = flags.port || env.PORT || 3456;
+    console.log(`⬡ Uplink started in background with watchdog (PID ${child.pid}).`);
+    console.log(`  → http://localhost:${port}`);
+    console.log(`  Auto-restarts on crash. Stop with: uplink-chat stop`);
+    process.exit(0);
+  } else if (flags.noWatchdog) {
+    // Foreground mode without watchdog — raw server, no auto-restart
+    const child = spawn(process.execPath, [serverPath], {
+      cwd: ROOT,
+      env,
+      stdio: 'inherit',
+    });
+
+    writeFileSync(PID_FILE, String(child.pid));
+
+    // Clean up pid file on exit
+    const cleanup = () => {
+      try { unlinkSync(PID_FILE); } catch {}
+    };
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+    child.on('exit', (code) => { cleanup(); process.exit(code || 0); });
+  } else {
+    // Foreground mode with watchdog (default) — auto-restarts on crash
+    const watchdogPath = join(ROOT, 'server', 'watchdog.js');
+    
+    const extraEnv = {};
+    if (flags.port) extraEnv.PORT = String(flags.port);
+    if (flags.host) extraEnv.UPLINK_HOST = flags.host;
+    
+    const child = spawn(process.execPath, [watchdogPath, JSON.stringify(extraEnv)], {
+      cwd: ROOT,
+      env,
+      stdio: 'inherit',
+    });
+
+    const port = flags.port || env.PORT || 3456;
+    console.log(`⬡ Uplink starting with watchdog (auto-restart enabled)`);
+    console.log(`  → http://localhost:${port}`);
+    console.log(`  Use --no-watchdog for raw server mode`);
+
+    process.on('SIGINT', () => { child.kill('SIGTERM'); });
+    process.on('SIGTERM', () => { child.kill('SIGTERM'); });
+    child.on('exit', (code) => { process.exit(code || 0); });
+  }
+}

package/middleware/error-handler.js

@@ -0,0 +1,69 @@
+// Centralized error handler middleware
+
+/**
+ * Structured error logging with timestamp, error type, and message
+ * @param {Error} err - The error object
+ * @param {string} requestId - Request ID for tracing
+ * @param {Object} req - Express request object for additional context
+ */
+function logError(err, requestId, req) {
+  const timestamp = new Date().toISOString();
+  const errorType = err.constructor?.name || err.name || 'Error';
+  
+  const logEntry = {
+    timestamp,
+    requestId,
+    errorType,
+    message: err.message,
+    code: err.code || 'UNKNOWN',
+    statusCode: err.statusCode || 500,
+    isOperational: err.isOperational || false,
+    stack: err.stack,
+    path: req?.path,
+    method: req?.method,
+    userAgent: req?.headers?.['user-agent'],
+    ip: req?.ip || req?.socket?.remoteAddress
+  };
+  
+  // Output as JSON for structured logging (can be ingested by log aggregators)
+  console.error(JSON.stringify(logEntry));
+}
+
+/**
+ * Get safe error response for client (never includes stack traces in production)
+ * @param {Error} err - The error object
+ * @returns {Object} Safe error response object
+ */
+function getSafeErrorResponse(err) {
+  const isProduction = process.env.NODE_ENV === 'production';
+  
+  if (err.isOperational) {
+    return {
+      error: true,
+      message: err.message,
+      code: err.code
+    };
+  }
+  
+  // Never expose stack traces or internal details to client in production
+  return {
+    error: true,
+    message: isProduction ? 'Internal server error' : err.message,
+    code: 'INTERNAL_ERROR',
+    ...(isProduction ? {} : { stack: err.stack })
+  };
+}
+
+function errorHandler(err, req, res, next) {
+  const requestId = req.headers['x-request-id'] || 'unknown';
+  
+  // Structured logging (server-side only, never sent to client)
+  logError(err, requestId, req);
+  
+  const statusCode = err.statusCode || 500;
+  const response = getSafeErrorResponse(err);
+  
+  return res.status(statusCode).json(response);
+}
+
+module.exports = errorHandler;

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@mooncompany/uplink-chat",
+  "version": "0.5.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Local-first AI chat with voice — talk to any LLM from your own machine",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "uplink-chat": "bin/uplink.js"
+  },
+  "files": [
+    "bin/",
+    "middleware/",
+    "public/css/",
+    "public/dist/",
+    "public/img/",
+    "public/js/",
+    "public/index.html",
+    "public/manifest.json",
+    "public/sw.js",
+    "public/favicon.svg",
+    "public/moon_texture.jpg",
+    "public/three.min.js",
+    "server/",
+    "server.js",
+    "utils/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/uplink.js start",
+    "build": "node scripts/build.js",
+    "dev": "esbuild public/js/app.js --bundle --outfile=public/dist/bundle.js --format=iife --platform=browser --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint public/js/**/*.js",
+    "lint:fix": "eslint public/js/**/*.js --fix",
+    "format": "prettier --write public/js/**/*.js",
+    "format:check": "prettier --check public/js/**/*.js",
+    "prepublishOnly": "node scripts/build.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mooncompany/uplink.git"
+  },
+  "keywords": [
+    "ai",
+    "chat",
+    "voice",
+    "tts",
+    "stt",
+    "local-first",
+    "assistant",
+    "openai",
+    "llm",
+    "openclaw"
+  ],
+  "author": "Moon Company <hello@moonco.pro>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mooncompany/uplink/issues"
+  },
+  "homepage": "https://uplinkchat.app",
+  "dependencies": {
+    "cors": "^2.8.6",
+    "dotenv": "^17.2.3",
+    "exceljs": "^4.4.0",
+    "express": "^4.18.2",
+    "express-rate-limit": "^8.2.1",
+    "file-type": "^21.3.0",
+    "mammoth": "^1.11.0",
+    "multer": "^2.0.2",
+    "pdf-parse": "^2.4.5",
+    "proper-lockfile": "^4.1.2",
+    "web-push": "^3.6.7",
+    "ws": "^8.19.0"
+  },
+  "optionalDependencies": {
+    "canvas": "^3.2.1",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
+    "prettier": "^3.3.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}