termsearch 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide A. Guglielmi
+
+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,205 @@
+# TermSearch - Personal Search Engine
+
+[![Status](https://img.shields.io/badge/Status-0.3.0-blue.svg)](#project-status)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
+[![Target](https://img.shields.io/badge/Target-Termux%20%2F%20Linux%20%2F%20macOS-green.svg)](https://termux.dev)
+[![npm](https://img.shields.io/badge/npm-termsearch-red.svg)](https://www.npmjs.com/package/termsearch)
+
+TermSearch is a privacy-first personal search engine installable with a single command on Termux, Linux, and macOS.
+Zero external dependencies, no Docker, no Python. AI is optional and configured entirely from the browser.
+
+Core capabilities:
+
+- Zero-config search via DuckDuckGo and Wikipedia — works immediately after install
+- Progressive enhancement: add Brave/Mojeek API keys, AI endpoints, or SearXNG when needed
+- Social profile scanner: GitHub, Bluesky, Reddit, Twitter/X, Instagram, YouTube, LinkedIn, TikTok, Telegram, Facebook
+- Torrent search: The Pirate Bay + 1337x with direct magnet extraction
+- Social search: Bluesky posts/actors + GDELT news
+- AI-powered 2-phase agentic summaries via any OpenAI-compatible endpoint
+- Vanilla HTML/CSS/JS frontend (~280KB, no build step, no framework)
+- Boot autostart: Termux:Boot, systemd --user, or launchd (macOS)
+
+## Project Status
+
+- Current line: `0.3.0`
+- Core is MIT — zero required API keys
+- AI features are optional, configured via Settings page in browser
+- Tested on: Ubuntu 24.04, Termux (Android 15/16)
+- macOS: compatible (launchd autostart), untested in production
+
+## Quickstart
+
+1. Install globally
+
+```bash
+npm install -g termsearch
+```
+
+2. Start
+
+```bash
+termsearch
+```
+
+3. Open browser at `http://localhost:3000`
+
+That's it. No configuration required for basic search.
+
+## CLI
+
+```bash
+termsearch                     # start + open browser (if not running: status)
+termsearch start               # start server in background
+termsearch start --fg          # start in foreground (debug/logs live)
+termsearch stop                # stop background server
+termsearch restart             # restart
+termsearch status              # show PID, URL, uptime
+termsearch doctor              # check Node version, data dir, HTTP health
+termsearch logs                # last 60 lines of server log
+termsearch logs -n 100         # last N lines
+termsearch open                # open browser
+termsearch autostart enable    # start at boot (Termux:Boot / systemd / launchd)
+termsearch autostart disable   # disable autostart
+termsearch help                # full command reference
+```
+
+Options:
+
+```bash
+--port=<port>                  # default: 3000
+--host=<host>                  # default: 127.0.0.1
+--data-dir=<path>              # default: ~/.termsearch/
+```
+
+## Progressive Enhancement
+
+| Level | Requirements | Features |
+|-------|-------------|---------|
+| **0** (zero-config) | None | DuckDuckGo + Wikipedia — works immediately |
+| **1** (API keys) | Brave/Mojeek key via Settings | Better and more diverse results |
+| **2** (AI) | Any OpenAI-compatible endpoint | Summaries, query refinement |
+| **3** (power user) | Own SearXNG instance | 40+ search engines |
+
+## AI Configuration
+
+Configure at **Settings → AI** in the browser. Supported endpoints:
+
+| Provider | API Base | Model | Key |
+|----------|----------|-------|-----|
+| **Localhost** (Ollama) | `http://localhost:11434/v1` | `qwen3.5:4b` or any | not required |
+| **Localhost** (LM Studio) | `http://localhost:1234/v1` | your loaded model | not required |
+| **Chutes.ai TEE** | `https://llm.chutes.ai/v1` | `deepseek-ai/DeepSeek-V3.2-TEE` | required |
+| **OpenAI** | `https://api.openai.com/v1` | `gpt-4o-mini` | required |
+| **API custom** | any OpenAI-compatible URL | your model | optional |
+
+All providers use the OpenAI-compatible `/chat/completions` format. Leave API key empty for local models.
+
+## Architecture
+
+```
+~/.termsearch/
+  config.json       user settings (saved via browser Settings page)
+  cache/            search + document cache (L1 RAM + L2 disk)
+  termsearch.pid    daemon PID
+  termsearch.log    server log
+
+src/
+  config/           config manager — load/save/defaults/env overrides
+  search/
+    providers/      DuckDuckGo, Wikipedia, Brave, Mojeek, SearXNG
+    engine.js       fan-out, merge, rank, cache
+    ranking.js      source diversity ranking
+    cache.js        tiered cache (L1 Map + L2 disk JSON)
+  fetch/
+    document.js     URL fetcher + HTML → readable text + site scan
+    ssrf-guard.js   SSRF protection
+  ai/
+    orchestrator.js 2-phase agentic summary flow
+    summary.js      prompt builder + response parser
+    query.js        query refinement
+    providers/
+      openai-compat.js  universal OpenAI-compatible client
+  profiler/
+    scanner.js      social profile scanner (10 platforms)
+  social/
+    scrapers.js     Twitter/Nitter, Instagram, YouTube, Facebook, LinkedIn, TikTok, Telegram
+    search.js       Bluesky posts/actors + GDELT news
+  torrent/
+    scrapers.js     TPB + 1337x scrapers + magnet extraction
+  autostart/
+    manager.js      boot autostart (Termux:Boot / systemd / launchd)
+  api/
+    routes.js       all API route handlers
+    middleware.js   rate limiting, security headers
+  server.js         Express app setup
+
+frontend/dist/      vanilla HTML/CSS/JS SPA (~280KB, no build step)
+```
+
+## API
+
+```
+GET  /api/health                     service status + enabled providers
+GET  /api/openapi.json               machine-readable API description
+GET  /api/search?q=...               web search
+GET  /api/search-stream?q=...        progressive SSE search
+POST /api/fetch                      fetch readable content from URL
+POST /api/ai-query                   AI query refinement
+POST /api/ai-summary                 AI summary with SSE streaming
+GET  /api/profiler?q=...             social profile scan (URL or @handle)
+GET  /api/social-search?q=...        Bluesky + GDELT news
+POST /api/torrent-search             torrent search (TPB + 1337x)
+POST /api/magnet                     extract magnet from torrent page URL
+POST /api/scan                       crawl site for query-matched pages
+GET  /api/config                     current config (keys masked)
+POST /api/config                     update and persist config
+POST /api/config/test-ai             test AI connection
+GET  /api/config/test-provider/:name test search provider
+GET  /api/autostart                  autostart status
+POST /api/autostart                  enable/disable autostart
+GET  /api/stats                      usage stats
+```
+
+## Environment Variables (optional, override Settings)
+
+```bash
+TERMSEARCH_PORT=3000
+TERMSEARCH_HOST=127.0.0.1
+TERMSEARCH_DATA_DIR=~/.termsearch/
+TERMSEARCH_AI_API_BASE=https://api.z.ai/api/coding/paas/v4
+TERMSEARCH_AI_API_KEY=
+TERMSEARCH_AI_MODEL=glm-4.7
+TERMSEARCH_BRAVE_API_KEY=
+TERMSEARCH_MOJEEK_API_KEY=
+TERMSEARCH_SEARXNG_URL=
+TERMSEARCH_GITHUB_TOKEN=
+TERMSEARCH_INSTAGRAM_SESSION=
+```
+
+## Termux
+
+```bash
+pkg install nodejs
+npm install -g termsearch
+termsearch
+```
+
+Enable autostart with Termux:Boot (install from F-Droid):
+
+```bash
+termsearch autostart enable
+```
+
+## Roadmap
+
+1. Persistent search stats counter
+2. Engine health tracking and failure classification
+3. Frontend profile viewer panel
+4. Frontend torrent results panel with magnet copy
+5. Agentic user-proxy (`/api/user-proxy`) for custom AI loops
+6. Packaged release on npm registry
+
+## License
+
+MIT — Copyright (c) 2026 Davide A. Guglielmi

package/bin/termsearch.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+// TermSearch CLI — personal search engine
+// Usage: termsearch [command] [options]
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, unlinkSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import path from 'path';
+import os from 'os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+const DAEMON_FLAG = '--_daemon_';   // internal flag: process is the background daemon
+const PKG_PATH    = path.join(__dirname, '../package.json');
+const SERVER_PATH = path.join(__dirname, '../src/server.js');
+
+const RESET  = '\x1b[0m';
+const GREEN  = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED    = '\x1b[31m';
+const CYAN   = '\x1b[36m';
+const BOLD   = '\x1b[1m';
+const DIM    = '\x1b[2m';
+
+function ok(msg)   { console.log(`  ${GREEN}✓${RESET} ${msg}`); }
+function warn(msg) { console.log(`  ${YELLOW}⚠${RESET} ${msg}`); }
+function err(msg)  { console.log(`  ${RED}✗${RESET} ${msg}`); }
+function info(msg) { console.log(`  ${CYAN}→${RESET} ${msg}`); }
+
+// ─── Package version ──────────────────────────────────────────────────────
+
+let VERSION = '0.3.0';
+try { VERSION = JSON.parse(readFileSync(PKG_PATH, 'utf8')).version || VERSION; } catch { /* ignore */ }
+
+// ─── Data dir + paths ─────────────────────────────────────────────────────
+
+function getDataDir() {
+  return process.env.TERMSEARCH_DATA_DIR || path.join(os.homedir(), '.termsearch');
+}
+
+function getPaths() {
+  const d = getDataDir();
+  return {
+    dir:  d,
+    pid:  path.join(d, 'termsearch.pid'),
+    log:  path.join(d, 'termsearch.log'),
+  };
+}
+
+// ─── PID helpers ──────────────────────────────────────────────────────────
+
+function readPid(pidPath) {
+  try { return parseInt(readFileSync(pidPath, 'utf8').trim(), 10); } catch { return null; }
+}
+
+function isRunning(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function getStatus() {
+  const { pid: pidPath } = getPaths();
+  const pid = readPid(pidPath);
+  const running = isRunning(pid);
+  return { pid: running ? pid : null, running };
+}
+
+// ─── Port / URL ───────────────────────────────────────────────────────────
+
+function getPort() { return process.env.TERMSEARCH_PORT || '3000'; }
+function getHost() { return process.env.TERMSEARCH_HOST || '127.0.0.1'; }
+function getUrl()  { return `http://${getHost()}:${getPort()}`; }
+
+// ─── CLI argument parsing ─────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args  = argv.slice(2);
+  const flags = {};
+  const cmds  = [];
+  for (const a of args) {
+    if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split('=');
+      flags[k] = v ?? true;
+    } else {
+      cmds.push(a);
+    }
+  }
+  return { cmd: cmds[0] || null, sub: cmds[1] || null, flags };
+}
+
+// ─── DAEMON MODE ─────────────────────────────────────────────────────────
+// When spawned with DAEMON_FLAG, just run the server (stdout → log file)
+
+if (process.argv.includes(DAEMON_FLAG)) {
+  // Apply env vars from flags
+  for (const arg of process.argv.slice(2)) {
+    if (arg === DAEMON_FLAG) continue;
+    const [k, v] = arg.split('=');
+    if (k === '--port' && v)     process.env.TERMSEARCH_PORT = v;
+    if (k === '--host' && v)     process.env.TERMSEARCH_HOST = v;
+    if (k === '--data-dir' && v) process.env.TERMSEARCH_DATA_DIR = v;
+  }
+
+  const { port, host } = await import(SERVER_PATH);
+  const dataDir = getDataDir();
+  const aiBase  = process.env.TERMSEARCH_AI_API_BASE || '';
+  const aiModel = process.env.TERMSEARCH_AI_MODEL || '';
+
+  console.log(`TermSearch v${VERSION} started`);
+  console.log(`Data: ${dataDir}`);
+  console.log(`URL:  http://${host}:${port}`);
+  if (aiBase && aiModel) console.log(`AI:   ${aiModel} @ ${aiBase}`);
+  process.exit ?? undefined; // keep running (server keeps the loop alive)
+  process.exit; // unreachable
+} else {
+  // ─── USER-FACING CLI ───────────────────────────────────────────────────
+  await runCli();
+}
+
+async function runCli() {
+  const { cmd, sub, flags } = parseArgs(process.argv);
+
+  // Apply flags to env
+  if (flags.port)       process.env.TERMSEARCH_PORT     = flags.port;
+  if (flags.host)       process.env.TERMSEARCH_HOST     = flags.host;
+  if (flags['data-dir']) process.env.TERMSEARCH_DATA_DIR = flags['data-dir'];
+
+  if (flags.help || flags.h || cmd === 'help') return printHelp();
+  if (flags.version || flags.v || cmd === 'version') {
+    console.log(`termsearch v${VERSION}`);
+    return;
+  }
+
+  switch (cmd) {
+    case 'start':    return cmdStart(flags);
+    case 'stop':     return cmdStop();
+    case 'restart':  return cmdRestart(flags);
+    case 'status':   return cmdStatus();
+    case 'open':     return cmdOpen();
+    case 'logs':     return cmdLogs(flags);
+    case 'doctor':   return cmdDoctor();
+    case 'autostart':return cmdAutostart(sub);
+    case null:       return cmdDefault(flags);
+    default:
+      err(`Unknown command: ${cmd}`);
+      console.log(`  Run ${BOLD}termsearch help${RESET} for usage`);
+      process.exit(1);
+  }
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────
+
+async function cmdStart(flags) {
+  const { running, pid } = getStatus();
+  if (running) {
+    warn(`Already running  (PID ${pid}  ${getUrl()})`);
+    return;
+  }
+
+  if (flags.fg || flags.foreground) {
+    // Foreground mode — import server directly
+    console.log('');
+    const { port, host } = await import(SERVER_PATH);
+    const dataDir = getDataDir();
+    const aiBase  = process.env.TERMSEARCH_AI_API_BASE || '';
+    const aiModel = process.env.TERMSEARCH_AI_MODEL || '';
+    console.log(`
+  ${BOLD}TermSearch v${VERSION}${RESET}
+  Personal search engine — privacy-first, local-first
+
+  ${GREEN}✓${RESET} Data: ${dataDir}
+  ${GREEN}✓${RESET} Search: DuckDuckGo + Wikipedia${
+    aiBase && aiModel ? `\n  ${GREEN}✓${RESET} AI: ${aiModel}` : `\n  ${DIM}○ AI: not configured (Settings → AI)${RESET}`
+  }
+
+  ${CYAN}→${RESET} ${BOLD}${getUrl()}${RESET}
+
+  Press Ctrl+C to stop
+`);
+    return;
+  }
+
+  // Background daemon
+  const paths = getPaths();
+  mkdirSync(paths.dir, { recursive: true });
+
+  const logFd = openSync(paths.log, 'a');
+  const passArgs = [];
+  if (process.env.TERMSEARCH_PORT)     passArgs.push(`--port=${process.env.TERMSEARCH_PORT}`);
+  if (process.env.TERMSEARCH_HOST)     passArgs.push(`--host=${process.env.TERMSEARCH_HOST}`);
+  if (process.env.TERMSEARCH_DATA_DIR) passArgs.push(`--data-dir=${process.env.TERMSEARCH_DATA_DIR}`);
+  passArgs.push(DAEMON_FLAG);
+
+  const child = spawn(process.execPath, [__filename, ...passArgs], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env: { ...process.env },
+  });
+  child.unref();
+
+  // Wait briefly to confirm it started
+  await sleep(600);
+  if (!isRunning(child.pid)) {
+    err('Failed to start — check logs: termsearch logs');
+    process.exit(1);
+  }
+
+  writeFileSync(paths.pid, String(child.pid));
+  ok(`Started  (PID ${child.pid})`);
+  info(`${BOLD}${getUrl()}${RESET}`);
+  info(`Logs: ${paths.log}`);
+}
+
+async function cmdStop() {
+  const paths = getPaths();
+  const { running, pid } = getStatus();
+  if (!running) {
+    warn('Not running');
+    return;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    await sleep(800);
+    if (isRunning(pid)) {
+      process.kill(pid, 'SIGKILL');
+      await sleep(300);
+    }
+    ok(`Stopped  (was PID ${pid})`);
+    try { unlinkSync(paths.pid); } catch { /* ignore */ }
+  } catch (e) {
+    err(`Stop failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+async function cmdRestart(flags) {
+  await cmdStop();
+  await sleep(400);
+  await cmdStart(flags);
+}
+
+function cmdStatus() {
+  const { running, pid } = getStatus();
+  const paths = getPaths();
+  console.log('');
+  if (running) {
+    ok(`${BOLD}Running${RESET}  (PID ${pid})`);
+    info(`${getUrl()}`);
+    info(`Data: ${paths.dir}`);
+    info(`Logs: ${paths.log}`);
+  } else {
+    warn('Stopped');
+    info(`Run ${BOLD}termsearch start${RESET} to start`);
+  }
+  console.log('');
+}
+
+function cmdOpen() {
+  const url = getUrl();
+  const isTermux = process.env.PREFIX?.includes('com.termux');
+  const opener = isTermux
+    ? ['termux-open-url', [url]]
+    : process.platform === 'darwin'
+      ? ['open', [url]]
+      : ['xdg-open', [url]];
+  try {
+    spawn(opener[0], opener[1], { stdio: 'ignore', detached: true }).unref();
+    info(`Opening ${url}`);
+  } catch {
+    info(`Open manually: ${BOLD}${url}${RESET}`);
+  }
+}
+
+function cmdLogs(flags) {
+  const { log: logPath } = getPaths();
+  if (!existsSync(logPath)) {
+    warn('No log file yet — start termsearch first');
+    return;
+  }
+  const lines = flags.n ? parseInt(flags.n, 10) : 60;
+  const content = readFileSync(logPath, 'utf8');
+  const tail = content.split('\n').slice(-lines).join('\n');
+  console.log(tail);
+}
+
+async function cmdDoctor() {
+  const paths = getPaths();
+  const { running, pid } = getStatus();
+  const port = getPort();
+  let allOk = true;
+
+  console.log('');
+  console.log(`${BOLD}  TermSearch v${VERSION} — doctor${RESET}`);
+  console.log('');
+
+  // Node.js version
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major >= 18) { ok(`Node.js ${process.versions.node}`); }
+  else { err(`Node.js ${process.versions.node} — requires ≥ 18`); allOk = false; }
+
+  // Platform
+  const isTermux = process.env.PREFIX?.includes('com.termux') || existsSync('/data/data/com.termux');
+  const platform = isTermux ? 'Termux' : process.platform === 'darwin' ? 'macOS' : process.platform === 'linux' ? 'Linux' : process.platform;
+  ok(`Platform: ${platform}`);
+
+  // Data dir
+  try {
+    const { mkdirSync, accessSync, constants } = await import('fs');
+    mkdirSync(paths.dir, { recursive: true });
+    accessSync(paths.dir, constants.W_OK);
+    ok(`Data dir: ${paths.dir}`);
+  } catch { err(`Data dir not writable: ${paths.dir}`); allOk = false; }
+
+  // Server status
+  if (running) { ok(`Server: running (PID ${pid})`); }
+  else { warn('Server: not running'); }
+
+  // HTTP health check (only if running)
+  if (running) {
+    try {
+      const ac = new AbortController();
+      setTimeout(() => ac.abort(), 3000);
+      const r = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: ac.signal });
+      if (r.ok) {
+        const h = await r.json();
+        ok(`HTTP: ${getUrl()} — providers: ${(h.providers || []).join(', ')}`);
+        if (h.ai_enabled) ok(`AI: configured (${h.ai_model})`);
+        else warn('AI: not configured (optional — Settings → AI)');
+      } else { err(`HTTP: ${r.status} from /api/health`); allOk = false; }
+    } catch (e) { err(`HTTP: cannot reach ${getUrl()} — ${e.message}`); allOk = false; }
+  }
+
+  console.log('');
+  if (allOk) { ok(`${GREEN}All checks passed${RESET}`); }
+  else { warn('Some checks failed — see above'); }
+  console.log('');
+}
+
+async function cmdAutostart(sub) {
+  const { getStatus: autostartStatus, setEnabled } = await import('../src/autostart/manager.js');
+  if (sub === 'enable' || sub === 'disable') {
+    try {
+      const status = setEnabled(sub === 'enable');
+      if (status.enabled) {
+        ok(`Autostart enabled  (${status.method})`);
+        info(`Config: ${status.config_path}`);
+      } else {
+        ok(`Autostart disabled`);
+      }
+      if (status.note) warn(status.note);
+    } catch (e) {
+      err(`Failed: ${e.message}`);
+    }
+    return;
+  }
+  // Show status
+  const status = autostartStatus();
+  console.log('');
+  info(`Platform : ${status.platform}`);
+  info(`Method   : ${status.method || 'N/A'}`);
+  info(`Status   : ${status.enabled ? `${GREEN}enabled${RESET}` : `${DIM}disabled${RESET}`}`);
+  if (status.config_path) info(`Config   : ${status.config_path}`);
+  if (status.note) warn(status.note);
+  if (!status.enabled) info(`Enable   : ${BOLD}termsearch autostart enable${RESET}`);
+  console.log('');
+}
+
+async function cmdDefault(flags) {
+  const { running, pid } = getStatus();
+  if (running) {
+    cmdStatus();
+  } else {
+    await cmdStart(flags);
+    if (getStatus().running) {
+      await sleep(300);
+      cmdOpen();
+    }
+  }
+}
+
+// ─── Help ─────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+${BOLD}TermSearch v${VERSION}${RESET}
+Personal search engine — privacy-first, local-first
+
+${BOLD}Usage:${RESET}
+  ${CYAN}termsearch${RESET}                       Start (if stopped) or show status
+  ${CYAN}termsearch${RESET} <command> [options]
+
+${BOLD}Commands:${RESET}
+  ${GREEN}start${RESET}                           Start server in background
+  ${GREEN}start --fg${RESET}                      Start in foreground (shows logs live)
+  ${GREEN}stop${RESET}                            Stop background server
+  ${GREEN}restart${RESET}                         Restart server
+  ${GREEN}status${RESET}                          Show running status + URL
+  ${GREEN}open${RESET}                            Open browser to http://localhost:3000
+  ${GREEN}logs${RESET} [-n <lines>]               Show server log (default: last 60 lines)
+  ${GREEN}doctor${RESET}                          Check Node.js, data dir, server health
+  ${GREEN}autostart${RESET}                       Show autostart (boot) status
+  ${GREEN}autostart enable${RESET}                Enable autostart at boot
+  ${GREEN}autostart disable${RESET}               Disable autostart at boot
+  ${GREEN}version${RESET}                         Print version
+  ${GREEN}help${RESET}                            Show this help
+
+${BOLD}Options:${RESET}
+  --port=<port>                   Port (default: 3000)
+  --host=<host>                   Host (default: 127.0.0.1)
+  --data-dir=<path>               Data dir (default: ~/.termsearch/)
+
+${BOLD}Examples:${RESET}
+  termsearch                      # start + open browser
+  termsearch start                # start in background
+  termsearch start --fg           # start in foreground
+  termsearch stop                 # stop
+  termsearch status               # check if running
+  termsearch logs -n 100          # last 100 log lines
+  termsearch autostart enable     # start at boot
+  termsearch --port=8080 start    # custom port
+
+${BOLD}Data:${RESET}  ~/.termsearch/config.json   (edit via Settings in browser)
+${BOLD}Logs:${RESET}  ~/.termsearch/termsearch.log
+${BOLD}URL:${RESET}   http://localhost:3000
+`);
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/config.example.json

@@ -0,0 +1,31 @@
+{
+  "port": 3000,
+  "host": "127.0.0.1",
+  "search": {
+    "providers": ["duckduckgo", "wikipedia"]
+  },
+  "ai": {
+    "enabled": false,
+    "api_base": "http://localhost:11434/v1",
+    "api_key": "",
+    "model": "qwen3.5:4b",
+    "_providers": {
+      "localhost_ollama": { "api_base": "http://localhost:11434/v1",         "model": "qwen3.5:4b" },
+      "localhost_lmstudio": { "api_base": "http://localhost:1234/v1",        "model": "your-model" },
+      "chutes_tee":       { "api_base": "https://llm.chutes.ai/v1",         "model": "deepseek-ai/DeepSeek-V3.2-TEE" },
+      "openai":           { "api_base": "https://api.openai.com/v1",        "model": "gpt-4o-mini" }
+    }
+  },
+  "brave": {
+    "enabled": false,
+    "api_key": ""
+  },
+  "mojeek": {
+    "enabled": false,
+    "api_key": ""
+  },
+  "searxng": {
+    "enabled": false,
+    "url": ""
+  }
+}