ava-engine 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,8 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/ava-engine"><img alt="npm" src="https://img.shields.io/npm/v/ava-engine?color=0A0A0C&label=npm"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/Mr-vero/ava-engine"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/Mr-vero/ava-engine/badge"></a>
   <a href="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml/badge.svg"></a>
   <a href="COMMERCIAL-LICENSE.md"><img alt="License: Ava Engine License (source-available)" src="https://img.shields.io/badge/license-source--available-0A0A0C"></a>
   <img alt="Node 22.9+" src="https://img.shields.io/badge/node-22.9%2B-4F46E5">
@@ -56,25 +58,25 @@ Requires **Node 22.9+** and desktop **Chrome**. One command installs Ava and wal
 npx ava-engine
 ```
 
-The setup wizard:
-1. checks your OpenRouter key (or lets you look around with no keys in MOCK mode);
-2. lets you pick Ava's voice;
-3. downloads offline speech recognition, with a progress bar;
-4. protects Ava with a password if other people will use it;
-5. starts Ava and opens **http://localhost:5190/app**.
+Set up **in your browser** (a step-by-step page) or **in the terminal**; both do the same:
+1. check your OpenRouter key (or look around with no keys, in MOCK mode);
+2. pick Ava's voice, and download the free offline voice (Kokoro, ~90 MB) with progress;
+3. download offline speech recognition, also with progress;
+4. protect Ava with a password if other people will use it;
+5. start Ava and open **http://localhost:5190/app**.
 
 After that, `npx ava-engine` just starts Ava.
 
 | Command | What it does |
 | --- | --- |
-| `npx ava-engine setup` | Re-run the wizard to change keys, voice, password or port |
+| `npx ava-engine setup` | Re-run setup to change keys, voice, password or port (`--web` for the browser, `--terminal` for here) |
 | `npx ava-engine doctor` | Check everything and get a fix for anything that's wrong |
-| `npx ava-engine models` | Add or remove offline speech models |
+| `npx ava-engine models` | Download speech models or the Kokoro voice (`models kokoro`) |
 | `npx ava-engine start --port 8080` | Start on another port |
 
 Settings live in `~/.ava-engine` (set `AVA_HOME` to move them). **Watch the demo locally** at `http://localhost:5190/app?demo=simple`.
 
-**For servers and scripts:** `OPENROUTER_API_KEY=… ACCESS_PASSWORD=… npx ava-engine setup --yes --models english-small` sets everything up without questions. There's also a Docker image; see [DEPLOY.md](DEPLOY.md).
+**On a server:** `npx ava-engine setup --web` works over SSH too. Forward the port (`ssh -L 5190:localhost:5190 your-server`) and open the link it prints. Or skip the questions: `OPENROUTER_API_KEY=… ACCESS_PASSWORD=… npx ava-engine setup --yes --models english-small,kokoro`. There's also a Docker image; see [DEPLOY.md](DEPLOY.md).
 
 <details>
 <summary><b>Working on Ava itself? Run from source</b></summary>

package/lib/asr.mjs

@@ -76,7 +76,11 @@ function getOffline() {
 }
 
 export function warmAsr() {
-  if (!asrAvailable()) { console.log("  sherpa ASR: no models found at", MODELS); return; }
+  if (!asrAvailable()) {
+    if (initErr) console.log("  speech recognition: the offline engine didn't load; using the browser's (run `npx ava-engine doctor`)");
+    else console.log("  speech recognition: using the browser's. For offline recognition: npx ava-engine models");
+    return;
+  }
   const e = availableEngines();
   if (e.includes("zipformer") && getOnline()) console.log("  sherpa ASR ready — English streaming (zipformer)");
   if (e.includes("sensevoice")) console.log("  sherpa ASR ready — multilingual (SenseVoice), lazy-loaded on first use");

package/lib/cli/apply.mjs

@@ -0,0 +1,58 @@
+// Turning setup answers into saved settings. Shared by the terminal wizard and
+// the browser setup, so both produce exactly the same configuration.
+import { MODELS_DIR, DEFAULT_PORT } from "./config.mjs";
+
+export const VOICES = {
+  kokoro: { label: "Kokoro", hint: "free, runs on this computer (~90 MB download)" },
+  elevenlabs: { label: "ElevenLabs", hint: "premium cloud voices, needs an ElevenLabs key" },
+  browser: { label: "The browser's voice", hint: "no setup, sounds robotic" },
+};
+
+/**
+ * answers: {
+ *   openrouterKey?: string | null   (null/"" → MOCK mode; undefined → keep the current key)
+ *   voice: "kokoro" | "elevenlabs" | "browser",
+ *   elevenKey?, elevenVoice?,
+ *   audience: "me" | "others", password?, proxy?: boolean,
+ *   port?: number
+ * }
+ */
+export function buildConfig(prev, a) {
+  const cfg = { ...prev };
+  const set = (k, v) => { if (v === undefined || v === null || v === "") delete cfg[k]; else cfg[k] = String(v); };
+
+  if (a.openrouterKey !== undefined) set("OPENROUTER_API_KEY", a.openrouterKey);
+
+  const voice = VOICES[a.voice] ? a.voice : "kokoro";
+  set("TTS_DEFAULT", voice);
+  set("KOKORO", voice === "kokoro" ? "on" : "off");
+  if (voice === "elevenlabs") {
+    if (a.elevenKey !== undefined) set("ELEVENLABS_API_KEY", a.elevenKey);
+    if (a.elevenVoice !== undefined) set("ELEVEN_VOICE_ID", a.elevenVoice);
+  }
+
+  if (a.audience === "others") {
+    set("HOST", "");
+    if (a.password !== undefined) set("ACCESS_PASSWORD", a.password);
+    set("TRUST_PROXY", a.proxy ? "1" : "");
+  } else {
+    set("HOST", "127.0.0.1");
+    set("ACCESS_PASSWORD", "");
+    set("TRUST_PROXY", "");
+  }
+
+  const port = Number(a.port);
+  set("PORT", Number.isInteger(port) && port > 0 && port < 65536 ? port : prev.PORT || DEFAULT_PORT);
+  set("AVA_MODELS_DIR", MODELS_DIR);
+  return cfg;
+}
+
+/** Problems that must be fixed before saving, as a list of human messages. */
+export function validateAnswers(a) {
+  const errors = [];
+  if (a.audience === "others" && (!a.password || String(a.password).length < 10)) errors.push("Choose an access password of at least 10 characters.");
+  if (a.voice === "elevenlabs" && a.elevenKey === "") errors.push("Add your ElevenLabs key, or pick another voice.");
+  const port = Number(a.port);
+  if (a.port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536)) errors.push("The port must be a number between 1 and 65535.");
+  return errors;
+}

package/lib/cli/main.mjs

@@ -14,17 +14,19 @@ const HELP = `
 
   Usage
     npx ava-engine              first run: setup wizard, then start. After that: start
-    npx ava-engine setup        (re)run the setup wizard
+    npx ava-engine setup        (re)run setup; asks: in the browser or the terminal
+    npx ava-engine setup --web  setup in your browser
+    npx ava-engine setup --terminal
     npx ava-engine start        start the server
     npx ava-engine doctor       check your setup and tell you what to fix
-    npx ava-engine models [..]  download speech models: ${Object.keys(MODEL_PACKS).join(", ")}
+    npx ava-engine models [..]  download models: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro (voice)
 
   Options
     --port <n>       port to listen on (default ${DEFAULT_PORT})
     --open           open the browser once Ava is up (default on a first run)
     --no-open        don't open the browser
     --yes            setup without questions, from environment variables
-    --models <a,b>   with --yes: model packs to download
+    --models <a,b>   with --yes: what to download, e.g. english-small,kokoro
     -v, --version    print the version
     -h, --help       show this help
 
@@ -40,6 +42,8 @@ function parseArgs(argv) {
     else if (a === "-v" || a === "--version") out.flags.version = true;
     else if (a === "--yes" || a === "-y") out.flags.yes = true;
     else if (a === "--open") out.flags.open = true;
+    else if (a === "--web") out.flags.web = true;
+    else if (a === "--terminal") out.flags.terminal = true;
     else if (a === "--no-open") out.flags.open = false;
     else if (a === "--port") out.flags.port = Number(argv[++i]);
     else if (a.startsWith("--port=")) out.flags.port = Number(a.slice(7));
@@ -116,7 +120,7 @@ export async function main(argv) {
     case "doctor": return doctor();
     case "start": await start({ port: flags.port, open: flags.open === true }); return null; // keeps running
     case "models": {
-      const { downloadPacks } = await import("./setup.mjs");
+      const { downloadPacks, downloadKokoro } = await import("./setup.mjs");
       let packs = args._.slice(1);
       if (!packs.length && interactive) {
         const p = await import("@clack/prompts");
@@ -126,19 +130,50 @@ export async function main(argv) {
         packs = sel;
       }
       if (!packs.length) packs = ["english-small"];
-      const bad = packs.filter((x) => !MODEL_PACKS[x]);
-      if (bad.length) { console.error(`✗ unknown model pack: ${bad.join(", ")}. Choose from: ${Object.keys(MODEL_PACKS).join(", ")}`); return 2; }
-      await downloadPacks(packs);
+      const bad = packs.filter((x) => !MODEL_PACKS[x] && x !== "kokoro");
+      if (bad.length) { console.error(`✗ unknown model: ${bad.join(", ")}. Choose from: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro`); return 2; }
+      if (packs.includes("kokoro")) await downloadKokoro();
+      await downloadPacks(packs.filter((x) => x !== "kokoro"));
       return 0;
     }
     case "setup":
     case "first-run": {
       const setup = await import("./setup.mjs");
-      if (!interactive) {
+      // --web needs a browser, not a terminal, so it works over SSH and from scripts too.
+      if (!interactive && !(flags.web && !flags.yes)) {
         await setup.runSetupNonInteractive({ models: flags.models || [], port: flags.port });
         if (cmd === "first-run") { await start({ port: flags.port, open: flags.open === true }); return null; }
         return 0;
       }
+      // Where to run the wizard: the browser (default) or this terminal.
+      let where = flags.web ? "web" : flags.terminal ? "terminal" : null;
+      if (!where) {
+        const p = await import("@clack/prompts");
+        console.log("");
+        p.intro(" ΛVΛ  Ava Engine setup ");
+        where = await p.select({
+          message: "Where would you like to set up Ava?",
+          options: [
+            { value: "web", label: "In my browser", hint: "recommended; a step-by-step page" },
+            { value: "terminal", label: "Here in the terminal" },
+          ],
+        });
+        if (p.isCancel(where)) { p.cancel("Setup cancelled. Nothing was changed."); return 0; }
+      }
+      if (where === "web") {
+        const { runWebSetup } = await import("./setup-server.mjs");
+        const r = await runWebSetup({
+          preferredPort: flags.port,
+          formPort: flags.port,
+          onReady: ({ url }) => {
+            console.log(`\n  Setup is open in your browser. If it didn't open, go to:\n  ${url}\n\n  (Keep this terminal open. Press Ctrl+C to cancel.)\n`);
+            if (flags.open !== false) openBrowser(url);
+          },
+        });
+        console.log("  Settings saved. Starting Ava…");
+        await start({ port: r.port, open: false }); // the port chosen on the page wins; the page redirects itself
+        return null;
+      }
       const r = await setup.runSetup();
       if (r.start) { await start({ port: flags.port || r.port, open: flags.open !== false }); return null; }
       return 0;

package/lib/cli/setup-server.mjs

@@ -0,0 +1,195 @@
+// `ava-engine setup --web`: the setup wizard as a page in your browser.
+//
+// A small, separate server that runs only during setup:
+//  - listens on 127.0.0.1 only,
+//  - every API call needs the one-time token from the URL the CLI opens,
+//  - rejects requests whose Host isn't localhost (stops DNS-rebinding attacks),
+//  - serves a strict Content-Security-Policy.
+// When you press "Launch", it saves the settings, closes, and the CLI starts Ava.
+
+import http from "node:http";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { buildConfig, validateAnswers, VOICES } from "./apply.mjs";
+import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.mjs";
+
+const PUBLIC = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public");
+const STATIC = new Map([
+  ["/setup", ["setup.html", "text/html; charset=utf-8"]],
+  ["/setup.js", ["setup.js", "text/javascript; charset=utf-8"]],
+  ["/setup.css", ["setup.css", "text/css; charset=utf-8"]],
+  ["/favicon.svg", ["favicon.svg", "image/svg+xml"]],
+  ["/fonts/inter-var.woff2", ["fonts/inter-var.woff2", "font/woff2"]],
+  ["/fonts/inter-tight-var.woff2", ["fonts/inter-tight-var.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-400.woff2", ["fonts/plex-mono-400.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-500.woff2", ["fonts/plex-mono-500.woff2", "font/woff2"]],
+]);
+const HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "no-referrer",
+  "Cache-Control": "no-store",
+  "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self' http://localhost:* http://127.0.0.1:*; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+};
+
+const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
+
+async function findPort(preferred) {
+  for (let p = preferred; p < preferred + 20; p++) if (await portFree(p, "127.0.0.1")) return p;
+  return 0; // let the OS pick
+}
+
+/**
+ * Run the browser setup. Resolves { start: true, port } once you press Launch.
+ * onReady({ url }) is called when the page is ready to open.
+ */
+export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so Kokoro downloads land in ~/.ava-engine/models
+  const prev = readConfig() || {};
+  const token = randomBytes(24).toString("base64url");
+  const jobs = {}; // id → { label, state: "running" | "done" | "error", pct, error }
+
+  const okToken = (req) => {
+    const t = Buffer.from(String(req.headers["x-setup-token"] || ""));
+    const want = Buffer.from(token);
+    return t.length === want.length && timingSafeEqual(t, want);
+  };
+
+  function startJob(id) {
+    if (jobs[id]?.state === "running" || jobs[id]?.state === "done") return;
+    if (id === "kokoro") {
+      jobs[id] = { label: `Kokoro voice (${KOKORO_SIZE})`, state: "running", pct: 0 };
+      if (kokoroInstalled()) { jobs[id] = { ...jobs[id], state: "done", pct: 100 }; return; }
+      loadKokoro({ onProgress: ({ pct }) => { jobs[id].pct = pct; } })
+        .then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+        .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+      return;
+    }
+    const spec = MODEL_PACKS[id];
+    jobs[id] = { label: `${spec.label} (${spec.size})`, state: "running", pct: 0 };
+    fetchPack(id, MODELS_DIR, (ev) => {
+      if (ev.phase === "download" && ev.total) jobs[id].pct = Math.min(99, Math.floor((ev.done / ev.total) * 100));
+      if (ev.phase === "extract") jobs[id].phase = "unpacking";
+    }).then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+      .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+  }
+
+  function state() {
+    const c = readConfig() || prev;
+    return {
+      configFile: CONFIG_FILE,
+      current: {
+        openrouterKey: mask(c.OPENROUTER_API_KEY),
+        voice: VOICES[c.TTS_DEFAULT] ? c.TTS_DEFAULT : "kokoro",
+        elevenKey: mask(c.ELEVENLABS_API_KEY),
+        elevenVoice: c.ELEVEN_VOICE_ID || "",
+        audience: c.ACCESS_PASSWORD ? "others" : "me",
+        hasPassword: !!c.ACCESS_PASSWORD,
+        proxy: c.TRUST_PROXY === "1",
+        port: formPort || Number(c.PORT) || DEFAULT_PORT,
+      },
+      voices: VOICES,
+      kokoro: { installed: kokoroInstalled(), size: KOKORO_SIZE },
+      packs: Object.fromEntries(Object.entries(MODEL_PACKS).map(([id, m]) => [id, { label: m.label, size: m.size, hint: m.hint }])),
+      installedPacks: installedPacks(MODELS_DIR),
+      suggestedPassword: suggestPassword(),
+      jobs,
+    };
+  }
+
+  let finish;
+  const finished = new Promise((r) => { finish = r; });
+  let listenPort = 0;
+
+  const server = http.createServer(async (req, res) => {
+    const send = (code, body, type = "application/json") => {
+      res.writeHead(code, { ...HEADERS, "Content-Type": type });
+      res.end(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+    };
+    // DNS-rebinding guard: only answer requests addressed to this machine.
+    const host = String(req.headers.host || "");
+    if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(host)) return send(403, { error: "forbidden host" });
+    let url;
+    try { url = new URL(req.url, "http://localhost"); } catch { return send(400, { error: "bad request" }); }
+
+    if (req.method === "GET" && STATIC.has(url.pathname)) {
+      const [file, type] = STATIC.get(url.pathname);
+      try { return send(200, await readFile(join(PUBLIC, file)), type); } catch { return send(404, "not found", "text/plain"); }
+    }
+    if (req.method === "GET" && url.pathname === "/") { res.writeHead(302, { Location: "/setup" }); return res.end(); }
+    if (!url.pathname.startsWith("/api/setup/")) return send(404, "not found", "text/plain");
+    if (!okToken(req)) return send(401, { error: "This setup link has expired. Run `npx ava-engine setup --web` for a new one." });
+
+    let body = {};
+    if (req.method === "POST") {
+      if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return send(415, { error: "expected application/json" });
+      const chunks = []; let size = 0;
+      for await (const c of req) { size += c.length; if (size > 64 * 1024) return send(413, { error: "too large" }); chunks.push(c); }
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch { return send(400, { error: "invalid JSON" }); }
+    }
+
+    try {
+      const route = `${req.method} ${url.pathname}`;
+      if (route === "GET /api/setup/state") return send(200, state());
+      if (route === "GET /api/setup/jobs") return send(200, { jobs, installedPacks: installedPacks(MODELS_DIR), kokoroInstalled: kokoroInstalled() });
+      if (route === "GET /api/setup/password") return send(200, { password: suggestPassword() });
+      if (route === "POST /api/setup/check") {
+        const key = String(body.key || "").trim();
+        if (key.length < 20) return send(200, { ok: false, error: "That doesn't look like a full key." });
+        const r = body.service === "elevenlabs" ? await checkElevenLabsKey(key) : await checkOpenRouterKey(key);
+        if (r.ok && r.label && /^sk-or/i.test(r.label)) delete r.label; // unnamed keys report a masked key as their label
+        return send(200, r);
+      }
+      if (route === "POST /api/setup/download") {
+        const id = String(body.id || "");
+        if (id !== "kokoro" && !MODEL_PACKS[id]) return send(400, { error: "unknown download" });
+        startJob(id);
+        return send(200, { ok: true, job: jobs[id] });
+      }
+      if (route === "POST /api/setup/save") {
+        const a = body.answers || {};
+        // "keep" means: leave the saved key as it is.
+        const answers = {
+          openrouterKey: a.mode === "mock" ? null : a.openrouterKey === "keep" ? undefined : String(a.openrouterKey || "") || null,
+          voice: a.voice,
+          elevenKey: a.elevenKey === "keep" ? undefined : a.elevenKey,
+          elevenVoice: a.elevenVoice,
+          audience: a.audience === "others" ? "others" : "me",
+          password: a.audience === "others" ? (a.password === "keep" ? prev.ACCESS_PASSWORD || readConfig()?.ACCESS_PASSWORD : a.password) : undefined,
+          proxy: !!a.proxy,
+          port: a.port,
+        };
+        const errors = validateAnswers(answers);
+        if (errors.length) return send(400, { error: errors.join(" ") });
+        const cfg = buildConfig(readConfig() || prev, answers);
+        const p = Number(cfg.PORT);
+        if (p !== listenPort && !(await portFree(p, cfg.HOST))) return send(409, { error: `Port ${p} is in use by another program. Pick another port.` });
+        writeConfig(cfg);
+        return send(200, { ok: true, port: p, url: `http://localhost:${p}/app`, configFile: CONFIG_FILE });
+      }
+      if (route === "POST /api/setup/finish") {
+        const cfg = readConfig();
+        if (!cfg) return send(400, { error: "Save your settings first." });
+        // Downloads still running (e.g. a voice you switched away from) keep going in
+        // this process after Ava starts; the page already waited for the ones you chose.
+        send(200, { ok: true, port: Number(cfg.PORT) || DEFAULT_PORT });
+        // let the response flush, then hand the port over to Ava
+        setTimeout(() => { server.closeAllConnections?.(); server.close(() => finish({ start: true, port: Number(cfg.PORT) || DEFAULT_PORT })); }, 150);
+        return;
+      }
+      return send(404, { error: "unknown endpoint" });
+    } catch (e) {
+      return send(500, { error: e.message });
+    }
+  });
+
+  listenPort = await findPort(preferredPort || Number(prev.PORT) || DEFAULT_PORT);
+  await new Promise((r) => server.listen(listenPort, "127.0.0.1", r));
+  listenPort = server.address().port;
+  const url = `http://localhost:${listenPort}/setup#token=${token}`;
+  onReady?.({ url, port: listenPort });
+  return finished;
+}