@tiens.nguyen/gonext-cli 1.0.350

package/model-doctor.mjs

@@ -0,0 +1,571 @@
+// Model bootstrap for the gonext CLI (task #127, Phase 3). Ensures the base CHAT model
+// (mlx_lm.server) is downloaded and RUNNING so a fresh Mac can answer without GoTerminal or
+// the Wizard doing it. The agent CODE model (Ollama) is probed + guided, not auto-pulled.
+//
+// BC3 (task #127): NEVER touch a model that is already running. The doctor probes first and
+// does nothing when a server answers — it will not kill, restart, re-port, or re-download a
+// model the user already runs (many run mlx_lm.server themselves on 8090, or point at a
+// remote box). Downloads happen only when the model dir is genuinely absent AND the user
+// opts in.
+import { spawn, execFile } from "node:child_process";
+import { open, mkdir, readdir, writeFile } from "node:fs/promises";
+import { homedir, totalmem } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
+const MIN_CHAT_RAM_GB = 16;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+// The RAG embedding model + server (task #127 — parity with the Wizard's model-embed step).
+// EMBED_PID_FILE / EMBED_LOG_FILE (which need DIR) are defined below, after DIR.
+export const EMBED_REPO = "mlx-community/Qwen3-Embedding-8B-4bit-DWQ";
+export const EMBED_DIR = join(homedir(), "mlx-models", "Qwen3-Embedding-8B-4bit-DWQ");
+export const EMBED_PORT = 8085;
+const EMBED_SCRIPT = fileURLToPath(new URL("./gonext_mlx_embed.py", import.meta.url));
+
+/** The python3 the worker uses to run its agent / model tooling (mirrors the daemon). */
+function python3Bin() {
+  return (
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim() ||
+    "python3"
+  );
+}
+
+/** True when `python3 -c "import <mod>"` succeeds — i.e. the module is installed. */
+function pyHasModule(mod) {
+  return new Promise((resolve) => {
+    execFile(python3Bin(), ["-c", `import ${mod}`], (err) => resolve(!err));
+  });
+}
+
+/** pip install -U <pkgs> with live progress (inherit stdio). Rejects on non-zero exit. */
+function pipInstall(pkgs, log) {
+  log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
+  return new Promise((resolve, reject) => {
+    const child = spawn(python3Bin(), ["-m", "pip", "install", "-U", ...pkgs], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`pip install ${pkgs.join(" ")} exited ${code}`))
+    );
+    child.on("error", reject);
+  });
+}
+
+/**
+ * The yellow RAM notice shown before the multi-GB model download (user request): the
+ * default 14B-4bit model wants a Mac with ≥16 GB. When the machine has less, add a plain
+ * line stating its detected amount. Pure (RAM passed in) so it's unit-testable.
+ * Returns already-colored lines; empty array only if `repo` is falsy.
+ */
+export function chatRamWarningLines(repo, totalBytes) {
+  if (!repo) return [];
+  const ramGb = Math.round((Number(totalBytes) || 0) / 1024 ** 3);
+  const name = String(repo).split("/").pop();
+  const out = [
+    yellow(`  ⚠ ${name} needs a Mac with at least ${MIN_CHAT_RAM_GB} GB of RAM to run well.`),
+  ];
+  if (ramGb > 0 && ramGb < MIN_CHAT_RAM_GB) {
+    out.push(
+      yellow(
+        `    This machine has about ${ramGb} GB — the model may run very slowly or fail to load.`
+      )
+    );
+  }
+  return out;
+}
+
+const DIR = join(homedir(), ".gonext");
+export const MODEL_PID_FILE = join(DIR, "model.pid");
+export const MODEL_LOG_FILE = join(DIR, "model.log");
+const EMBED_PID_FILE = join(DIR, "embed.pid");
+const EMBED_LOG_FILE = join(DIR, "embed.log");
+
+// The default base chat model (task #127 decision): matches the Wizard's model-chat step.
+export const DEFAULT_CHAT_REPO = "mlx-community/Qwen3-14B-4bit";
+export const DEFAULT_CHAT_DIR = join(homedir(), "mlx-models", "Qwen3-14B-4bit");
+export const DEFAULT_CHAT_PORT = 8082;
+
+// ---- pure helpers (unit-tested offline) -------------------------------------------------
+
+/** The port from a base URL, or null. "http://127.0.0.1:8082/v1" → 8082. */
+export function parsePort(baseUrl) {
+  try {
+    const u = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`);
+    if (u.port) return Number(u.port);
+    return u.protocol === "https:" ? 443 : 80;
+  } catch {
+    const m = String(baseUrl || "").match(/:(\d{2,5})(?:\/|$)/);
+    return m ? Number(m[1]) : null;
+  }
+}
+
+/** True when the URL points at this machine (loopback/LAN) — only then can we START it. */
+export function isLocalModelUrl(baseUrl) {
+  let host = "";
+  try {
+    host = new URL(String(baseUrl || "").includes("://") ? baseUrl : `http://${baseUrl}`)
+      .hostname.toLowerCase()
+      .replace(/\.$/, "");
+  } catch {
+    return false;
+  }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (!host) return false;
+  if (["localhost", "0.0.0.0", "::", "::1"].includes(host)) return true;
+  if (/^127(\.\d{1,3}){3}$/.test(host)) return true;
+  if (
+    /^(10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){2}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|169\.254(\.\d{1,3}){2})$/.test(
+      host
+    )
+  )
+    return true;
+  if (host.includes(":") && (host.startsWith("fe80:") || /^f[cd]/.test(host))) return true;
+  if (/\.(local|localdomain|lan|home|internal)$/.test(host)) return true;
+  return !host.includes(".") && !host.includes(":");
+}
+
+/** Normalize a base URL to its root (strip a trailing /v1 and slashes). */
+export function modelRoot(baseUrl) {
+  return String(baseUrl || "").replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+
+// ---- probing + process control ----------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** True when an OpenAI-compatible model server answers GET {base}/v1/models. */
+export async function probeModelServer(baseUrl, { timeoutMs = 3000 } = {}) {
+  const root = modelRoot(baseUrl);
+  if (!root) return false;
+  try {
+    const res = await fetch(`${root}/v1/models`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function which(cmd) {
+  return new Promise((resolve) => {
+    execFile("command", ["-v", cmd], { shell: "/bin/sh" }, (err, stdout) =>
+      resolve(!err && Boolean(String(stdout).trim()))
+    );
+  });
+}
+
+/** True when the model directory exists and is non-empty. */
+export async function modelDirReady(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start mlx_lm.server for `modelDir` on `port`, DETACHED (logs to model.log, pidfile). Waits
+ * until the server answers /v1/models (up to waitMs). No-op + { started:false } when a
+ * server already answers on that port (BC3). Returns { started, ready, pid?, reason? }.
+ */
+export async function startChatModelServer({ modelDir, port, waitMs = 120_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await which("mlx_lm.server"))) {
+    return {
+      started: false,
+      ready: false,
+      reason: "mlx_lm.server not found — install it: pip install mlx-lm",
+    };
+  }
+  await mkdir(DIR, { recursive: true });
+  const out = await open(MODEL_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn("mlx_lm.server", ["--model", modelDir, "--port", String(port)], {
+      detached: true,
+      stdio: ["ignore", out.fd, out.fd],
+      env: process.env,
+    });
+    pid = child.pid;
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(MODEL_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await out.close();
+  }
+  log(`  starting mlx_lm.server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) {
+      return { started: true, ready: true, pid };
+    }
+  }
+  return {
+    started: true,
+    ready: false,
+    pid,
+    reason: `model server did not answer within ${Math.round(waitMs / 1000)}s (still loading? see ${MODEL_LOG_FILE})`,
+  };
+}
+
+/**
+ * Download an MLX model repo to a local dir via the Hugging Face CLI. Streams progress to
+ * the terminal (inherit stdio) because it's a multi-GB, several-minute step. Resolves
+ * { ok } / rejects with guidance when `hf` is missing.
+ */
+export async function downloadModel({ repo, dir, log = () => {} }) {
+  if (!(await which("hf"))) {
+    throw new Error(
+      "the Hugging Face CLI (hf) is required to download the model. Install it with: pip install huggingface_hub"
+    );
+  }
+  log(`  downloading ${repo} → ${dir} (multi-GB, keep this open)…`);
+  return new Promise((resolve, reject) => {
+    const child = spawn("hf", ["download", repo, "--local-dir", dir], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve({ ok: true }) : reject(new Error(`hf download exited ${code}`))
+    );
+    child.on("error", (e) => reject(e));
+  });
+}
+
+/** Fetch the account's resolved model config from /agent-payload (best-effort). */
+async function fetchModelConfig(apiBase, workerKey) {
+  try {
+    const res = await fetch(`${apiBase.replace(/\/+$/, "")}/api/worker/agent-payload`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify({ messages: [{ role: "user", content: "ping" }] }),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data?.payload ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Phase-3 orchestration (task #127). Ensures the base CHAT model is running (starting a
+ * local mlx_lm.server, downloading first if the dir is missing and the user opts in), and
+ * probes the CODE model, giving guidance for a remote one. BC3-safe throughout: an
+ * already-answering server is left untouched.
+ *
+ * `log(str)` prints; `confirm(question, defaultYes)→bool` gates the multi-GB download and
+ * the model-server start (non-interactive callers pass a confirm that returns false, so the
+ * doctor only PROBES + advises and never downloads/starts unattended).
+ */
+export async function runDoctor({ apiBase, workerKey, log, confirm }) {
+  const p = (await fetchModelConfig(apiBase, workerKey)) ?? {};
+
+  // Step 0: the agent's PYTHON deps must be present or every agent turn crashes at import
+  // — and the model download/start needs `hf`/`mlx-lm`. Ensure these FIRST (task #127:
+  // parity with the Wizard's pip-mlx-lm / pip-agent-libs / hf-cli steps). Fatal-ish: if the
+  // core framework is missing, say so, but keep going so the model steps still run.
+  const deps = await ensureAgentDeps({ log, confirm });
+
+  // Chat model: prefer the account's configured URL; fall back to the default local one.
+  const configuredChat = String(p.agentBaseURL || "").trim();
+  const chatUrl = configuredChat || `http://127.0.0.1:${DEFAULT_CHAT_PORT}`;
+  const chatPort = parsePort(chatUrl) || DEFAULT_CHAT_PORT;
+  // Review H2: never serve a model the account didn't configure. Only the KNOWN default is
+  // auto-downloadable; for a specifically-named other model we start its dir if present but
+  // won't substitute Qwen3-14B. "default_model" is the direct-URL sentinel (the loaded
+  // model), which we treat as the default. modelId empty (fresh account) → default too.
+  const modelId = String(p.agentModelId || "").trim();
+  const isDefaultModel =
+    !modelId || modelId === "default_model" || /qwen3-?14b/i.test(modelId);
+  const chatDir = isDefaultModel
+    ? DEFAULT_CHAT_DIR
+    : join(homedir(), "mlx-models", modelId.replace(/[^A-Za-z0-9._-]/g, "-"));
+  const chatRepo = isDefaultModel ? DEFAULT_CHAT_REPO : null; // null = not auto-downloadable
+
+  // The chat handling sets `chat` but never returns early — the code-model check below is
+  // independent and must run even when the user declines the chat-model setup.
+  let chat = "checked";
+  log("");
+  log("  Checking the base chat model…");
+  if (await probeModelServer(chatUrl)) {
+    log(`  ✓ chat model already running at ${modelRoot(chatUrl)} — leaving it alone.`);
+    chat = "already-running";
+  } else if (configuredChat && !isLocalModelUrl(chatUrl)) {
+    // Configured but REMOTE and not answering — we can't start a model on another machine.
+    log(`  ⚠ your chat model server (${modelRoot(chatUrl)}) isn't answering.`);
+    log("    It's remote, so start it there — this machine can't launch it.");
+    chat = "remote";
+  } else {
+    // Local (or unconfigured → default local): ensure the RIGHT model, then offer to start.
+    const dir = chatDir;
+    let dirReady = await modelDirReady(dir);
+    if (!dirReady && !chatRepo) {
+      // A specifically-named, non-default model we don't know how to fetch — DON'T
+      // substitute the default. Tell the user how to bring their own (review H2).
+      log(`  ⚠ your account uses the chat model "${modelId}", which isn't the built-in`);
+      log(`    default, so I can't auto-download it. Put it at ${dir} (or any dir) and run:`);
+      log(`      mlx_lm.server --model <that dir> --port ${chatPort}`);
+      chat = "unknown-model";
+    } else if (!dirReady) {
+      // Yellow RAM notice before the multi-GB download, THEN the confirm (user request).
+      for (const line of chatRamWarningLines(chatRepo, totalmem())) log(line);
+      const yes = await confirm(
+        `Download the base chat model ${chatRepo} (~8 GB) to ${dir}?`,
+        true
+      );
+      if (!yes) {
+        log("  Skipped. To do it yourself:");
+        log(`      hf download ${chatRepo} --local-dir ${dir}`);
+        log(`      mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "skipped";
+      } else {
+        try {
+          await downloadModel({ repo: chatRepo, dir, log });
+          dirReady = true;
+        } catch (e) {
+          log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+          chat = "download-failed";
+        }
+      }
+    }
+    if (dirReady && chat === "checked") {
+      const yes = await confirm(`Start the chat model server on port ${chatPort} now?`, true);
+      if (!yes) {
+        log(`  Skipped. Start it later: mlx_lm.server --model ${dir} --port ${chatPort}`);
+        chat = "not-started";
+      } else {
+        // Review M2: don't block the caller (the REPL) for a full cold model load — that's
+        // minutes. Wait only long enough to confirm the server launched and didn't crash
+        // (~20s); if it's still loading, say so and return. The first agent turn will wait
+        // for it. A missing binary / immediate exit still surfaces as an error.
+        const r = await startChatModelServer({
+          modelDir: dir,
+          port: chatPort,
+          waitMs: 20_000,
+          log,
+        });
+        if (r.ready) {
+          log(`  ✓ chat model is up on port ${chatPort}.`);
+          chat = "started";
+        } else if (r.started) {
+          log(`  … chat model is loading in the background on port ${chatPort} (large model —`);
+          log(`    the first answer may take a minute). Watch it: gonext-cli logs`);
+          chat = "loading";
+        } else {
+          log(`  ⚠ ${r.reason}`);
+          chat = "start-failed";
+        }
+      }
+    }
+  }
+
+  // Code model (Ollama): probe + guide only — never auto-pull (BC3 + bounded scope).
+  const codeUrl = String(p.codingBaseURL || "").trim();
+  const codeModel = String(p.codingModelId || "").trim();
+  if (codeUrl) {
+    log("");
+    log("  Checking the agent code model…");
+    if (await probeModelServer(codeUrl)) {
+      log(`  ✓ code model server is up at ${modelRoot(codeUrl)}.`);
+    } else if (isLocalModelUrl(codeUrl)) {
+      log(`  ⚠ local code model server (${modelRoot(codeUrl)}) isn't answering.`);
+      if (codeModel) log(`    Start Ollama and pull it:  ollama serve &  ollama pull ${codeModel}`);
+    } else {
+      log(`  ⚠ your code model runs on a remote server (${modelRoot(codeUrl)}) that isn't`);
+      log(`    answering. Start it there${codeModel ? ` (ollama pull ${codeModel})` : ""}.`);
+    }
+  }
+
+  // RAG (task #127: the user wants the terminal RAG-ready). Ensure the embedding model +
+  // server so rag_index / rag_search work. Uses the account's configured embed URL when
+  // local, else the default local one on EMBED_PORT.
+  const rag = await ensureRag({ p, log, confirm });
+
+  return { chat, deps, rag };
+}
+
+/**
+ * Ensure the agent's required runtime deps (task #127 — parity with the Wizard's pip steps).
+ * python3 can't be auto-installed (guidance only); hf / mlx-lm / smolagents+openai are
+ * offered via pip. Each install is confirmed. Returns a status map; missing deps are
+ * reported, never silently ignored — the agent hard-fails without smolagents+openai.
+ */
+export async function ensureAgentDeps({ log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking the agent's dependencies…");
+  // python3 — the whole agent runs on it; we can't install it for the user.
+  if (!(await pyHasModule("sys"))) {
+    log(`  ⚠ ${python3Bin()} not found. Install Python 3 (Xcode Command Line Tools or`);
+    log("    python.org), then run `gonext-cli doctor` again.");
+    out.python3 = "missing";
+    return out; // nothing else can be installed without python
+  }
+  out.python3 = "ok";
+
+  const ensurePkg = async (key, probeMod, pkgs, question) => {
+    if (await probeMod()) {
+      out[key] = "present";
+      return;
+    }
+    if (!(await confirm(question, true))) {
+      out[key] = "skipped";
+      log(`  Skipped ${pkgs.join(" ")} — install later: ${python3Bin()} -m pip install -U ${pkgs.join(" ")}`);
+      return;
+    }
+    try {
+      await pipInstall(pkgs, log);
+      out[key] = "installed";
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out[key] = "failed";
+    }
+  };
+
+  // hf CLI (model downloads). `huggingface_hub` provides the `hf` command.
+  await ensurePkg(
+    "hf",
+    () => which("hf"),
+    ["huggingface_hub"],
+    "Install the Hugging Face CLI (needed to download models)?"
+  );
+  // mlx-lm — runs the local chat + embedding model servers.
+  await ensurePkg("mlxLm", () => pyHasModule("mlx_lm"), ["mlx-lm"], "Install mlx-lm (runs the local model servers)?");
+  // The agent framework itself — WITHOUT this every agent turn crashes at import.
+  await ensurePkg(
+    "agentLibs",
+    async () => (await pyHasModule("smolagents")) && (await pyHasModule("openai")),
+    ["smolagents", "openai"],
+    "Install the agent framework (smolagents + openai) — required to run the agent?"
+  );
+  if (out.agentLibs === "skipped" || out.agentLibs === "failed") {
+    log(yellow("  ⚠ Without smolagents + openai the agent can't run — install them before asking a question."));
+  }
+  return out;
+}
+
+/**
+ * Start the MLX embeddings server (gonext_mlx_embed.py) DETACHED on `port` for `modelDir`,
+ * with its own pidfile/log. No-op + { ready:true } when one already answers (BC3). Waits up
+ * to waitMs for /v1/models to respond. Mirrors startChatModelServer.
+ */
+export async function startEmbedServer({ modelDir, port, waitMs = 60_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await pyHasModule("mlx_lm"))) {
+    return { started: false, ready: false, reason: "mlx-lm not installed (pip install mlx-lm)" };
+  }
+  await mkdir(DIR, { recursive: true });
+  const outLog = await open(EMBED_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn(
+      python3Bin(),
+      [EMBED_SCRIPT, "--model", modelDir, "--port", String(port), "--host", "127.0.0.1"],
+      { detached: true, stdio: ["ignore", outLog.fd, outLog.fd], env: process.env }
+    );
+    pid = child.pid;
+    await writeFile(EMBED_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await outLog.close();
+  }
+  log(`  starting embeddings server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) return { started: true, ready: true, pid };
+  }
+  return { started: true, ready: false, pid, reason: `embeddings server still loading (see ${EMBED_LOG_FILE})` };
+}
+
+/**
+ * Ensure RAG is ready for the agent terminal (task #127): boto3 (cloud/S3 storage), the
+ * embedding model, and a running embeddings server. Uses the account's configured embed URL
+ * when it's local; otherwise the default local server on EMBED_PORT. BC3: an already-running
+ * embed server is left alone. Returns a status map.
+ */
+export async function ensureRag({ p, log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking RAG (agent knowledge base)…");
+  // boto3 — needed only for CLOUD (S3) RAG; local RAG stores on disk. Cheap + harmless, so
+  // offer it so cloud RAG works later without another setup pass.
+  if (!(await pyHasModule("boto3"))) {
+    if (await confirm("Install boto3 (needed only if you use cloud/S3 RAG)?", true)) {
+      try {
+        await pipInstall(["boto3"], log);
+        out.boto3 = "installed";
+      } catch (e) {
+        log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+        out.boto3 = "failed";
+      }
+    } else out.boto3 = "skipped";
+  } else out.boto3 = "present";
+
+  // Embed server URL: the account's configured local one, else the default local server.
+  const configuredEmbed = String(p?.ragEmbedUrl || "").trim();
+  const embedUrl =
+    configuredEmbed && isLocalModelUrl(configuredEmbed)
+      ? configuredEmbed
+      : `http://127.0.0.1:${EMBED_PORT}`;
+  const embedPort = parsePort(embedUrl) || EMBED_PORT;
+
+  if (await probeModelServer(embedUrl)) {
+    log(`  ✓ embeddings server already running at ${modelRoot(embedUrl)} — leaving it alone.`);
+    out.embed = "already-running";
+    return out;
+  }
+  if (configuredEmbed && !isLocalModelUrl(configuredEmbed)) {
+    log(`  ⚠ your embeddings server (${modelRoot(configuredEmbed)}) is remote and isn't`);
+    log("    answering. Start it there — this machine can't launch it.");
+    out.embed = "remote";
+    return out;
+  }
+  // Download the embed model if missing.
+  if (!(await modelDirReady(EMBED_DIR))) {
+    if (!(await confirm(`Download the RAG embedding model ${EMBED_REPO.split("/").pop()} (~4 GB)?`, true))) {
+      log("  Skipped. To do it yourself:");
+      log(`      hf download ${EMBED_REPO} --local-dir ${EMBED_DIR}`);
+      log(`      gonext-cli embed --model ${EMBED_DIR} --port ${embedPort}`);
+      out.embed = "skipped-model";
+      return out;
+    }
+    try {
+      await downloadModel({ repo: EMBED_REPO, dir: EMBED_DIR, log });
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out.embed = "download-failed";
+      return out;
+    }
+  }
+  if (!(await confirm(`Start the RAG embeddings server on port ${embedPort} now?`, true))) {
+    log(`  Skipped. Start it later: gonext-cli embed --model ${EMBED_DIR} --port ${embedPort}`);
+    out.embed = "not-started";
+    return out;
+  }
+  const r = await startEmbedServer({ modelDir: EMBED_DIR, port: embedPort, log });
+  if (r.ready) {
+    log(`  ✓ embeddings server is up on port ${embedPort}.`);
+    out.embed = "started";
+  } else if (r.started) {
+    log(`  … embeddings server is loading in the background on port ${embedPort}.`);
+    out.embed = "loading";
+  } else {
+    log(`  ⚠ ${r.reason}`);
+    out.embed = "start-failed";
+  }
+  return out;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tiens.nguyen/gonext-cli",
+  "version": "1.0.350",
+  "description": "GoNext CLI — the gonext terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiennsloit/gonext.git"
+  },
+  "homepage": "https://github.com/tiennsloit/gonext#readme",
+  "bugs": {
+    "url": "https://github.com/tiennsloit/gonext/issues"
+  },
+  "bin": {
+    "gonext-cli": "./gonext-cli.mjs",
+    "gonext-local-worker": "./gonext-cli.mjs",
+    "gonext": "./gonext-repl.mjs"
+  },
+  "scripts": {
+    "test": "python3 -m unittest discover tests -v && node --test tests/*.test.mjs",
+    "test:js": "node --test tests/*.test.mjs",
+    "deploy:local": "npm install -g .",
+    "run": "gonext-cli",
+    "publish:org": "npm publish --access public"
+  },
+  "files": [
+    "gonext-cli.mjs",
+    "gonext-repl.mjs",
+    "device-login.mjs",
+    "daemon-control.mjs",
+    "model-doctor.mjs",
+    "coding-key-prompt.mjs",
+    "gonext_probe_agent.py",
+    "gonext_agent_chat.py",
+    "gonext_transcribe.py",
+    "gonext_mlx_embed.py",
+    "thinking_words.txt",
+    "README.md",
+    "launchd/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "openai": "^4.77.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}