ava-engine 0.0.0-stage → 0.2.0

package/lib/asr.mjs

@@ -0,0 +1,147 @@
+// Offline streaming speech-to-text — free, on-device, no key. Two engines the
+// user picks before the call:
+//   - "zipformer"  : English streaming zipformer. Live word-by-word partials.
+//   - "sensevoice" : SenseVoice multilingual (zh/en/ja/ko/yue). Utterance-based
+//                    via Silero VAD; cased + punctuated; more accurate on accents.
+
+import { createRequire } from "node:module";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const __dir = dirname(fileURLToPath(import.meta.url));
+const MODELS = process.env.AVA_MODELS_DIR || join(__dir, "../models"); // the CLI points this at ~/.ava-engine/models
+
+// zipformer: prefer the larger model, fall back to the 20M; SHERPA_MODEL_DIR overrides
+const ZIP_CANDIDATES = [
+  process.env.SHERPA_MODEL_DIR,
+  join(MODELS, "sherpa-onnx-streaming-zipformer-en-2023-06-26"),
+  join(MODELS, "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17"),
+].filter(Boolean);
+const ZIP_DIR = ZIP_CANDIDATES.find((d) => existsSync(join(d, "tokens.txt")));
+const SV_DIR = join(MODELS, "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17");
+const VAD_MODEL = join(MODELS, "silero_vad.onnx");
+
+let sherpa = null, online = null, offline = null, initErr = null;
+
+function loadSherpa() {
+  if (!sherpa && !initErr) { try { sherpa = require("sherpa-onnx-node"); } catch (e) { initErr = e; console.log("  sherpa unavailable:", e.message); } }
+  return sherpa;
+}
+
+// Which engines have their model files on disk.
+export function availableEngines() {
+  const e = [];
+  if (ZIP_DIR) e.push("zipformer");
+  if (existsSync(join(SV_DIR, "tokens.txt")) && existsSync(VAD_MODEL)) e.push("sensevoice");
+  return e;
+}
+export function asrAvailable() { return !initErr && availableEngines().length > 0; }
+export function defaultEngine() { const e = availableEngines(); return e.includes("zipformer") ? "zipformer" : (e[0] || null); }
+export const ENGINE_LABELS = { zipformer: "English · streaming", sensevoice: "Multilingual · SenseVoice" };
+
+function pick(dir, kind, preferInt8) {
+  const files = readdirSync(dir).filter((f) => f.startsWith(kind) && f.endsWith(".onnx"));
+  const int8 = files.find((f) => f.includes("int8")), fp = files.find((f) => !f.includes("int8"));
+  return join(dir, preferInt8 ? int8 || fp : fp || int8);
+}
+
+function getOnline() {
+  if (online || !ZIP_DIR) return online;
+  const s = loadSherpa(); if (!s) return null;
+  online = new s.OnlineRecognizer({
+    featConfig: { sampleRate: 16000, featureDim: 80 },
+    modelConfig: {
+      transducer: { encoder: pick(ZIP_DIR, "encoder", true), decoder: pick(ZIP_DIR, "decoder", false), joiner: pick(ZIP_DIR, "joiner", true) },
+      tokens: join(ZIP_DIR, "tokens.txt"), numThreads: 2, provider: "cpu",
+    },
+    decodingMethod: "greedy_search",
+    enableEndpoint: true, rule1MinTrailingSilence: 2.4, rule2MinTrailingSilence: 0.9, rule3MinUtteranceLength: 20,
+  });
+  return online;
+}
+function getOffline() {
+  if (offline) return offline;
+  const s = loadSherpa(); if (!s) return null;
+  offline = new s.OfflineRecognizer({
+    featConfig: { sampleRate: 16000, featureDim: 80 },
+    modelConfig: {
+      senseVoice: { model: pick(SV_DIR, "model", true), language: process.env.SENSEVOICE_LANG || "en", useInverseTextNormalization: 1 },
+      tokens: join(SV_DIR, "tokens.txt"), numThreads: 2, provider: "cpu",
+    },
+    decodingMethod: "greedy_search",
+  });
+  return offline;
+}
+
+export function warmAsr() {
+  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");
+}
+
+// SenseVoice text can carry <|lang|><|emo|> tags; strip them.
+function cleanSV(t) { return String(t || "").replace(/<\|[^|]*\|>/g, "").replace(/\s+/g, " ").trim(); }
+// ws hands us pooled Buffers at arbitrary byte offsets — read alignment-safe.
+function toFloat32(buf) {
+  if (buf instanceof Int16Array) { const o = new Float32Array(buf.length); for (let i = 0; i < buf.length; i++) o[i] = buf[i] / 32768; return o; }
+  const n = Math.floor(buf.length / 2); const o = new Float32Array(n); for (let i = 0; i < n; i++) o[i] = buf.readInt16LE(i * 2) / 32768; return o;
+}
+
+/** One live transcription session for a WebSocket connection. */
+export function createAsrSession(engine) {
+  const eng = availableEngines().includes(engine) ? engine : defaultEngine();
+  if (!eng) return null;
+  return eng === "sensevoice" ? sensevoiceSession() : zipformerSession();
+}
+
+function zipformerSession() {
+  const rec = getOnline(); if (!rec) return null;
+  const stream = rec.createStream(); let last = "";
+  return {
+    engine: "zipformer",
+    feed(buf) {
+      const samples = toFloat32(buf);
+      stream.acceptWaveform({ sampleRate: 16000, samples });
+      while (rec.isReady(stream)) rec.decode(stream);
+      const text = (rec.getResult(stream).text || "").trim();
+      const out = {};
+      if (rec.isEndpoint(stream)) { if (text) out.final = text; rec.reset(stream); last = ""; }
+      else if (text && text !== last) { last = text; out.partial = text; }
+      return out;
+    },
+    close() { try { stream.free && stream.free(); } catch {} },
+  };
+}
+
+function sensevoiceSession() {
+  const rec = getOffline(); const s = loadSherpa(); if (!rec || !s) return null;
+  const vad = new s.Vad({
+    sileroVad: { model: VAD_MODEL, threshold: 0.5, minSilenceDuration: 0.5, minSpeechDuration: 0.25, windowSize: 512 },
+    sampleRate: 16000, numThreads: 1, provider: "cpu",
+  }, 30);
+  return {
+    engine: "sensevoice",
+    feed(buf) {
+      vad.acceptWaveform(toFloat32(buf));
+      const out = {};
+      while (!vad.isEmpty()) {
+        const seg = vad.front(); vad.pop();
+        const st = rec.createStream();
+        st.acceptWaveform({ sampleRate: 16000, samples: seg.samples });
+        rec.decode(st);
+        const text = cleanSV(rec.getResult(st).text);
+        try { st.free && st.free(); } catch {}
+        if (text) out.final = out.final ? out.final + " " + text : text;
+      }
+      return out;
+    },
+    close() { try { vad.free && vad.free(); } catch {} },
+  };
+}

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/config.mjs

@@ -0,0 +1,95 @@
+// Where the installed CLI keeps its state, and small helpers the commands share.
+//
+//   ~/.ava-engine/.env      settings (API keys, password, port…), mode 600
+//   ~/.ava-engine/models/   offline speech-to-text models
+//
+// AVA_HOME moves the whole folder (handy for servers, Docker and tests).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import { randomInt } from "node:crypto";
+
+export const AVA_HOME = process.env.AVA_HOME || join(homedir(), ".ava-engine");
+export const CONFIG_FILE = join(AVA_HOME, ".env");
+export const MODELS_DIR = join(AVA_HOME, "models");
+export const DEFAULT_PORT = 5190;
+
+/** Parse a .env file into an object (no expansion, last value wins). */
+export function readConfig(file = CONFIG_FILE) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (!m) continue;
+    let v = m[2];
+    if (/^".*"$/.test(v)) v = v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+const quote = (v) => (/^[A-Za-z0-9_@%+=:,./-]*$/.test(v) ? v : `"${String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+
+/** Write settings to the config file (readable only by you). Empty values are dropped. */
+export function writeConfig(values, file = CONFIG_FILE) {
+  mkdirSync(AVA_HOME, { recursive: true });
+  const lines = [
+    "# Ava Engine settings, written by `ava-engine setup`. Edit freely, or re-run setup.",
+    "# Every option is documented at https://github.com/Mr-vero/ava-engine/blob/main/.env.example",
+    "",
+    ...Object.entries(values).filter(([, v]) => v !== undefined && v !== null && v !== "").map(([k, v]) => `${k}=${quote(v)}`),
+    "",
+  ];
+  writeFileSync(file, lines.join("\n"), { mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch {}
+}
+
+/** Check an OpenRouter key. Returns { ok, label?, limit?, error? }. */
+export async function checkOpenRouterKey(key) {
+  try {
+    const r = await fetch("https://openrouter.ai/api/v1/key", { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) });
+    if (r.status === 401 || r.status === 403) return { ok: false, error: "OpenRouter rejected this key" };
+    if (!r.ok) return { ok: false, error: `OpenRouter answered ${r.status}` };
+    const d = (await r.json()).data || {};
+    return { ok: true, label: d.label, limit: d.limit, usage: d.usage };
+  } catch (e) {
+    return { ok: false, error: `couldn't reach OpenRouter (${e.name === "TimeoutError" ? "timed out" : e.message})`, offline: true };
+  }
+}
+
+/** Check an ElevenLabs key. Returns { ok, error? }. */
+export async function checkElevenLabsKey(key) {
+  try {
+    const r = await fetch("https://api.elevenlabs.io/v1/user", { headers: { "xi-api-key": key }, signal: AbortSignal.timeout(10_000) });
+    if (r.status === 401 || r.status === 403) return { ok: false, error: "ElevenLabs rejected this key" };
+    return r.ok ? { ok: true } : { ok: false, error: `ElevenLabs answered ${r.status}` };
+  } catch (e) {
+    return { ok: false, error: `couldn't reach ElevenLabs (${e.message})`, offline: true };
+  }
+}
+
+/** True if nothing is listening on the port. */
+export function portFree(port, host) {
+  return new Promise((res) => {
+    const s = createServer();
+    s.once("error", () => res(false));
+    s.listen({ port, host }, () => s.close(() => res(true)));
+  });
+}
+
+export function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch {}
+}
+
+/** A random password like "k7fq-9xm4-r3pz": 12 characters, 60 bits, no look-alike letters. */
+export function suggestPassword() {
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789"; // 31 chars: no i, l, o, 0, 1
+  const group = () => Array.from({ length: 4 }, () => alphabet[randomInt(alphabet.length)]).join("");
+  return `${group()}-${group()}-${group()}`;
+}

package/lib/cli/main.mjs

@@ -0,0 +1,187 @@
+// The `ava-engine` command.
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { AVA_HOME, CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, checkOpenRouterKey, portFree, openBrowser } from "./config.mjs";
+import { MODEL_PACKS, installedPacks } from "../fetch-models.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const VERSION = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+
+const HELP = `
+  ΛVΛ  Ava Engine ${VERSION}: a screen-aware voice agent
+
+  Usage
+    npx ava-engine              first run: setup wizard, then start. After that: start
+    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 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: what to download, e.g. english-small,kokoro
+    -v, --version    print the version
+    -h, --help       show this help
+
+  Settings live in ${CONFIG_FILE}
+  (set AVA_HOME to keep them somewhere else). Docs: https://github.com/Mr-vero/ava-engine
+`;
+
+function parseArgs(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") out.flags.help = true;
+    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));
+    else if (a === "--models") out.flags.models = String(argv[++i] || "").split(",").filter(Boolean);
+    else if (a.startsWith("--")) throw new Error(`unknown option ${a} (see --help)`);
+    else out._.push(a);
+  }
+  if (out.flags.port !== undefined && !(Number.isInteger(out.flags.port) && out.flags.port > 0 && out.flags.port < 65536)) throw new Error("--port needs a number between 1 and 65535");
+  return out;
+}
+
+/** Load the saved settings into the environment (real env vars win), then run the server. */
+async function start({ port, open }) {
+  const cfg = readConfig() || {};
+  for (const [k, v] of Object.entries(cfg)) if (process.env[k] === undefined) process.env[k] = v;
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+  if (port) process.env.PORT = String(port);
+  const p = Number(process.env.PORT) || DEFAULT_PORT;
+  if (!(await portFree(p, process.env.HOST))) {
+    console.error(`\n  ✗ Port ${p} is already in use. Try: npx ava-engine start --port ${p + 1}\n`);
+    process.exit(1);
+  }
+  await import("../../server.mjs");
+  if (open) {
+    const url = `http://localhost:${p}/app`;
+    for (let i = 0; i < 50; i++) { // wait until the server answers, then open the app
+      try { if ((await fetch(`http://127.0.0.1:${p}/api/health`)).ok) break; } catch {}
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    openBrowser(url);
+  }
+}
+
+async function doctor() {
+  const cfg = readConfig();
+  const rows = [];
+  const add = (ok, label, fix) => rows.push({ ok, label, fix });
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  add(maj > 22 || (maj === 22 && min >= 9) ? "ok" : "fail", `Node ${process.versions.node}`, "Ava needs Node 22.9 or newer: https://nodejs.org");
+  add(cfg ? "ok" : "fail", cfg ? `Settings: ${CONFIG_FILE}` : "No settings yet", "Run: npx ava-engine setup");
+  const c = cfg || {};
+  if (c.OPENROUTER_API_KEY) {
+    const r = await checkOpenRouterKey(c.OPENROUTER_API_KEY);
+    add(r.ok ? "ok" : r.offline ? "warn" : "fail", r.ok ? `OpenRouter key works${r.limit != null ? ` (limit $${r.limit}, used $${(r.usage ?? 0).toFixed(2)})` : ""}` : r.error, "Check the key at https://openrouter.ai/keys, then: npx ava-engine setup");
+  } else add("warn", "No OpenRouter key: MOCK mode (canned replies)", "Add one with: npx ava-engine setup");
+  if (c.TTS_DEFAULT === "elevenlabs" && !c.ELEVENLABS_API_KEY) add("fail", "Voice is ElevenLabs but there's no ElevenLabs key", "Run: npx ava-engine setup");
+  const packs = installedPacks(c.AVA_MODELS_DIR || MODELS_DIR);
+  add(packs.length ? "ok" : "warn", packs.length ? `Speech models: ${packs.map((x) => MODEL_PACKS[x].label).join(", ")}` : "No offline speech models: browser speech recognition only", "Download with: npx ava-engine models english-small");
+  try { createRequire(import.meta.url)("sherpa-onnx-node"); add("ok", "Speech engine (sherpa-onnx) loads"); }
+  catch (e) { add(packs.length ? "fail" : "warn", `Speech engine (sherpa-onnx) doesn't load: ${e.message.split("\n")[0]}`, "Reinstall: npx --yes ava-engine@latest (Linux also needs libgomp1)"); }
+  if (c.HOST !== "127.0.0.1" && !c.ACCESS_PASSWORD) add("warn", "Reachable from the network with NO password: anyone can spend your API credit", "Run setup and choose a password, or set HOST=127.0.0.1");
+  const port = Number(c.PORT) || DEFAULT_PORT;
+  const free = await portFree(port, c.HOST);
+  add(free ? "ok" : "warn", `Port ${port} ${free ? "is free" : "is in use (maybe Ava is already running)"}`, `Use another: npx ava-engine start --port ${port + 1}`);
+
+  const icon = { ok: "✓", warn: "!", fail: "✗" };
+  console.log(`\n  ΛVΛ  Ava Engine doctor (${VERSION})\n`);
+  for (const r of rows) console.log(`  ${icon[r.ok]} ${r.label}${r.ok !== "ok" && r.fix ? `\n      → ${r.fix}` : ""}`);
+  const failed = rows.some((r) => r.ok === "fail");
+  console.log(failed ? "\n  Some checks failed. Fix those, then run doctor again.\n" : "\n  Ready. Start Ava with: npx ava-engine\n");
+  return failed ? 1 : 0;
+}
+
+export async function main(argv) {
+  let args;
+  try { args = parseArgs(argv); } catch (e) { console.error(`✗ ${e.message}`); return 2; }
+  const { flags } = args;
+  if (flags.version) { console.log(VERSION); return 0; }
+  const cmd = args._[0] || (flags.help ? "help" : existsSync(CONFIG_FILE) ? "start" : "first-run");
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && !flags.yes;
+
+  switch (cmd) {
+    case "help": console.log(HELP); return 0;
+    case "doctor": return doctor();
+    case "start": await start({ port: flags.port, open: flags.open === true }); return null; // keeps running
+    case "models": {
+      const { downloadPacks, downloadKokoro } = await import("./setup.mjs");
+      let packs = args._.slice(1);
+      if (!packs.length && interactive) {
+        const p = await import("@clack/prompts");
+        const have = installedPacks(MODELS_DIR);
+        const sel = await p.multiselect({ message: "Which speech models?", required: false, initialValues: have, options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })) });
+        if (p.isCancel(sel)) return 0;
+        packs = sel;
+      }
+      if (!packs.length) packs = ["english-small"];
+      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");
+      // --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;
+    }
+    default:
+      console.error(`✗ unknown command "${cmd}" (see --help)`);
+      return 2;
+  }
+}
+
+export { AVA_HOME };