@tiens.nguyen/gu-cli 1.0.707 → 1.0.708

package/gu-repl.mjs

@@ -24,13 +24,13 @@
  * Commands: /exit  /model  /reset  /help   Ctrl-C stops following the current run.
  */
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
-import { existsSync, statSync, readFileSync } from "node:fs";
+import { existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 // FIRST, before anything that could itself fail on an old runtime: npm only WARNS about
 // `engines`, so an unsupported Node installs fine and then breaks somewhere unrelated.
 import { requireSupportedNode } from "./node-version.mjs";
 requireSupportedNode();
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PassThrough } from "node:stream";
@@ -795,6 +795,8 @@ const COMMANDS = [
   { name: "/proxy", usage: "/proxy [show|set|on|off|clear|test]", desc: "route MODEL calls through an HTTP proxy (local calls always go direct)" },
   { name: "/s3", usage: "/s3 [test]", desc: "set up the S3 bucket the RAG index lives in, and check the AWS keys work" },
   { name: "/context-window", usage: "/context-window [tokens|auto]", desc: "tell gu how big the coding model's context is — hosted models cannot be probed" },
+  { name: "/save-settings", usage: "/save-settings [path]", desc: "write this account's coding providers, models and key NAMES to a file (no secrets)" },
+  { name: "/load-settings", usage: "/load-settings [path]", desc: "read that file back on another machine — asks before it replaces anything" },
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/help", desc: "list these commands" },
@@ -6093,6 +6095,138 @@ async function chooseModel() {
 // The settings row as the WORKER sees it (X-Worker-Key, no Firebase). This is the only route a
 // Client Expert machine has to its own settings — there is no web app pointed at that API — so
 // anything a command needs to show or change has to come through here.
+/**
+ * `/save-settings [path]` and `/load-settings [path]` — move a setup between machines (#244).
+ *
+ * WHAT TRAVELS: the coding providers and their model lists, the agent model, and the NAMES of the
+ * API keys. What does not travel is the keys themselves — the API will not hand them over (see
+ * settings-transfer.mjs for why, and why that is right), so loading asks for the ones the target
+ * account is missing. The file is therefore safe to copy about, which is the whole point of it.
+ *
+ * NOT THE CURRENT CHOICE. Which model this account codes with stays as it is on the machine being
+ * loaded into: a file that moves your models should not quietly move your coder too.
+ */
+const SETTINGS_FILE_DEFAULT = join(homedir(), "gu-settings.json");
+
+/** The path a command was given, or the default. Quotes stripped: people paste paths with them. */
+function settingsPathFrom(line, word) {
+  const typed = line.slice(word.length).trim().replace(/^['"]|['"]$/g, "");
+  if (!typed) return SETTINGS_FILE_DEFAULT;
+  const expanded = typed.startsWith("~/") ? join(homedir(), typed.slice(2)) : typed;
+  return resolve(expanded);
+}
+
+async function runSaveSettingsCommand(line) {
+  const st = await import("./settings-transfer.mjs");
+  const file = settingsPathFrom(line, "/save-settings");
+  console.log("");
+  const settings = await withPendingStatus("reading your model settings", fetchWorkerSettings);
+  if (!settings) {
+    console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was written.\n`));
+    return;
+  }
+  const keys = (await fetchCodingKeys()) ?? [];
+  const doc = st.buildTransfer({ settings, keys, host: hostname() });
+  if (!doc.codingBackends.length && !doc.agentModel.url && !doc.agentModel.name) {
+    console.log(GUTTER + dim("  this account has no coding providers and no agent model set — nothing to save.\n"));
+    return;
+  }
+  // ASK BEFORE OVERWRITING. The default path is one everybody shares, so the second machine to
+  // save would otherwise eat the first machine's file without a word.
+  if (existsSync(file)) {
+    const ok = (await ask(`${file} exists — overwrite it? [y/N] `)).trim().toLowerCase();
+    if (ok !== "y" && ok !== "yes") {
+      console.log(GUTTER + dim("  left it alone.\n"));
+      return;
+    }
+  }
+  try {
+    // 0600: it names your providers and your key names. Not secret, but nobody else's business.
+    writeFileSync(file, JSON.stringify(doc, null, 2) + "\n", { mode: 0o600 });
+  } catch (e) {
+    console.log(GUTTER + red(`  could not write ${file}: ${e instanceof Error ? e.message : e}\n`));
+    return;
+  }
+  const models = doc.codingBackends.reduce((n, b) => n + b.models.length, 0);
+  console.log(GUTTER + accent(`  saved to ${file}`));
+  console.log(
+    GUTTER +
+      dim(`  ${doc.codingBackends.length} provider${doc.codingBackends.length === 1 ? "" : "s"}, ${models} model${models === 1 ? "" : "s"}, ${doc.keys.length} key name${doc.keys.length === 1 ? "" : "s"} — no secrets.`),
+  );
+  console.log(GUTTER + dim("  load it on the other machine with  /load-settings " + file + "\n"));
+}
+
+async function runLoadSettingsCommand(line) {
+  const st = await import("./settings-transfer.mjs");
+  const file = settingsPathFrom(line, "/load-settings");
+  console.log("");
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    console.log(GUTTER + red(`  no file at ${file}`));
+    console.log(GUTTER + dim("  /load-settings <path>, or save one first with /save-settings.\n"));
+    return;
+  }
+  // VALIDATED BEFORE ANYTHING IS TOUCHED: a settings file applied halfway is worse than one
+  // refused, because the half that landed is the half nobody re-reads.
+  const parsed = st.validateTransfer(text);
+  if (!parsed.ok) {
+    console.log(GUTTER + red(`  ${parsed.problem}`));
+    console.log(GUTTER + dim(`  file: ${file}\n`));
+    return;
+  }
+  const current = await withPendingStatus("reading your model settings", fetchWorkerSettings);
+  if (!current) {
+    console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was changed.\n`));
+    return;
+  }
+  const keys = (await fetchCodingKeys()) ?? [];
+  const plan = st.planLoad(parsed.value, { ...current, keys });
+  console.log(GUTTER + dim(`  from ${file}${parsed.value.savedOn ? ` (saved on ${parsed.value.savedOn})` : ""}`));
+  for (const l of plan.lines) console.log(GUTTER + dim("  " + l));
+  if (parsed.carriesSecrets) {
+    console.log(GUTTER + yellow("  this file contains API keys in plain text — delete it when you are done."));
+  }
+  console.log("");
+  const go = (await ask("  apply this? [y/N] ")).trim().toLowerCase();
+  if (go !== "y" && go !== "yes") {
+    console.log(GUTTER + dim("  nothing changed.\n"));
+    return;
+  }
+  const md = await import("./model-doctor.mjs");
+  // `current` so a provider this account already has keeps its row id — see toSettingsPatch.
+  const patch = st.toSettingsPatch(parsed.value, current);
+  const saved = Object.keys(patch).length
+    ? await md.saveWorkerSettings(apiBase, workerKey, patch)
+    : true;
+  if (!saved) {
+    console.log(GUTTER + red("  the API refused the settings — nothing was changed.\n"));
+    return;
+  }
+  console.log(GUTTER + accent(`  applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}.`));
+
+  // THE KEYS, AFTER the settings — each needs the row it belongs to, and the rows only exist
+  // once the API has minted their ids.
+  const fresh = (await fetchWorkerSettings()) ?? {};
+  const rows = Array.isArray(fresh.agentCodingBackends) ? fresh.agentCodingBackends : [];
+  const rowIdForUrl = (url) => {
+    const hit = rows.find((r) => String(r?.url ?? "").trim().toLowerCase() === String(url).trim().toLowerCase());
+    return hit?.id ?? "";
+  };
+  for (const k of plan.missingKeys) {
+    const where = k.backendUrl ? ` for ${k.backendUrl}` : "";
+    const typed = k.key || (await ask(`  key "${k.name}"${k.tail ? ` (…${k.tail})` : ""}${where} — paste it, or Enter to skip: `)).trim();
+    if (!typed) {
+      console.log(GUTTER + dim(`  skipped ${k.name} — add it later with ctrl+k.`));
+      continue;
+    }
+    const id = await addCodingKey(k.name, typed, k.backendUrl ? rowIdForUrl(k.backendUrl) : "");
+    console.log(GUTTER + (id ? accent(`  added ${k.name}.`) : red(`  could not add ${k.name}.`)));
+  }
+  console.log(GUTTER + dim("  pick a coding model with /model.\n"));
+}
+
 async function fetchWorkerSettings() {
   try {
     const r = await fetch(`${apiBase}/api/worker/settings`, {
@@ -10536,6 +10670,14 @@ async function main() {
       await runS3Command(line);
       continue;
     }
+    if (line === "/save-settings" || line.startsWith("/save-settings ")) {
+      await runSaveSettingsCommand(line);
+      continue;
+    }
+    if (line === "/load-settings" || line.startsWith("/load-settings ")) {
+      await runLoadSettingsCommand(line);
+      continue;
+    }
     if (line === "/test-auto") {
       sessionTestAuto = !sessionTestAuto;
       await saveSession(cwd, history); // persist the choice for this folder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.707",
+  "version": "1.0.708",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "rag-selftest.mjs",
     "cli-token.mjs",
     "credential-recovery.mjs",
+    "settings-transfer.mjs",
     "device-login.mjs",
     "daemon-control.mjs",
     "poll-errors.mjs",

package/settings-transfer.mjs

@@ -0,0 +1,253 @@
+/**
+ * MOVING A SETUP BETWEEN MACHINES — the file /save-settings writes and /load-settings reads (#244).
+ *
+ * WHAT IT CARRIES: the coding backends (the list /model picks from), the agent model, and the
+ * IDENTITY of each API key. What it deliberately does not carry is the keys themselves.
+ *
+ * WHY NO SECRETS, since this is the first question anyone asks of a "save my settings" file: the API
+ * will not give them to us. GET /api/worker/coding-keys returns maskCodingKeys() — id, name, last
+ * four characters — and says why on the route: it is the one place that lists credentials, so it is
+ * the one place that could turn a leaked worker key into "dump every key I own". The only route that
+ * returns a real secret returns exactly one, the key a given job or provider would be handed. A save
+ * could walk that route once per provider and harvest the lot, which is precisely the thing the
+ * masking exists to prevent — and it would put them in a file that then sits in Downloads.
+ *
+ * So the file names the keys and loading asks for the ones the target account is missing. The
+ * side-effect is the good kind: this file is safe to copy, email, or commit.
+ *
+ * ROW IDS NEVER TRAVEL. They identify a row WITHIN one account — a folder's saved pick, a job's
+ * record of which key it used, the account default all name one — so another account's ids would
+ * either collide with a row already there or silently re-point a folder at a different provider.
+ * The file therefore names providers by URL, which means the same thing on every machine.
+ *
+ * ON LOADING, A PROVIDER THIS ACCOUNT ALREADY HAS KEEPS ITS OWN ID (see toSettingsPatch). Minting a
+ * fresh one would strand every key bound to the old row: a key whose row is gone is ineligible
+ * everywhere and filtered out of every picker, so it can never be selected, used or deleted again.
+ *
+ * THE CURRENT CHOICE IS NOT SAVED, by instruction and by safety: agentCodingDefaultKind and
+ * agentCodingDefaultBackendId stay as they are on the machine being loaded into. A file that moves
+ * your models should not also decide which one you are coding with.
+ */
+
+/** Bumped only when an older gu could not read a newer file correctly. */
+export const FILE_VERSION = 1;
+
+/** The kinds the API's own type allows (CodingBackendKind). */
+const KINDS = ["", "ollama", "openai", "local"];
+
+const isHttpUrl = (v) => typeof v === "string" && /^https?:\/\/\S+$/i.test(v.trim());
+const isStr = (v) => typeof v === "string";
+const clean = (v) => (typeof v === "string" ? v.trim() : "");
+
+/**
+ * The object /save-settings writes.
+ *
+ * `settings` is the account's settings as the API returns them; `keys` is the masked list. Neither
+ * is trusted to be well-formed — a machine that has never set a coder has no backends at all.
+ */
+export function buildTransfer({ settings = {}, keys = [], now = new Date(), host = "" } = {}) {
+  const rows = Array.isArray(settings.agentCodingBackends) ? settings.agentCodingBackends : [];
+  const backends = rows
+    .filter((r) => r && typeof r === "object")
+    .map((r) => ({
+      kind: KINDS.includes(r.kind) ? r.kind : "",
+      url: clean(r.url),
+      defaultModel: clean(r.defaultModel),
+      models: Array.isArray(r.models) ? r.models.filter(isStr).map((m) => m.trim()).filter(Boolean) : [],
+      enabled: r.enabled !== false,
+    }));
+  // A key's row id means nothing on another account; the provider's URL means the same everywhere.
+  const urlForRowId = new Map(rows.filter((r) => r?.id).map((r) => [r.id, clean(r.url)]));
+  const keyList = (Array.isArray(keys) ? keys : [])
+    .filter((k) => k && typeof k === "object" && clean(k.name))
+    .map((k) => ({
+      name: clean(k.name),
+      tail: clean(k.tail),
+      ...(urlForRowId.get(k.backendId) ? { backendUrl: urlForRowId.get(k.backendId) } : {}),
+    }));
+  return {
+    gu: "settings",
+    version: FILE_VERSION,
+    // Said in the file, because someone will open it and wonder.
+    note: "Models and providers only. This file contains NO API keys — gu asks for those when you load it.",
+    savedAt: new Date(now).toISOString(),
+    ...(host ? { savedOn: host } : {}),
+    codingBackends: backends,
+    agentModel: { url: clean(settings.agentModelUrl), name: clean(settings.agentModelName) },
+    keys: keyList,
+  };
+}
+
+/**
+ * Read a file's text and say either what it means or what is wrong with it.
+ *
+ * ONE PROBLEM, NAMED. Everything is checked before anything is applied, and the first real problem
+ * refuses the whole file: a settings file applied halfway is worse than one rejected, because the
+ * half that landed is the half nobody reads back.
+ */
+export function validateTransfer(text) {
+  let doc;
+  try {
+    doc = JSON.parse(String(text));
+  } catch {
+    return { ok: false, problem: "that file is not JSON — is it the file gu saved?" };
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return { ok: false, problem: "that file is not a gu settings file (expected a JSON object)." };
+  }
+  if (doc.gu !== "settings") {
+    return { ok: false, problem: 'that file is not a gu settings file (no "gu": "settings" marker).' };
+  }
+  if (doc.version !== FILE_VERSION) {
+    return {
+      ok: false,
+      problem: `that file is version ${JSON.stringify(doc.version)}; this gu writes and reads version ${FILE_VERSION}. Update gu, or save it again from the machine that wrote it.`,
+    };
+  }
+  const rows = doc.codingBackends;
+  if (rows !== undefined && !Array.isArray(rows)) {
+    return { ok: false, problem: "codingBackends must be a list." };
+  }
+  const backends = [];
+  const seen = new Set();
+  for (const [i, r] of (rows ?? []).entries()) {
+    const at = `codingBackends[${i}]`;
+    if (!r || typeof r !== "object" || Array.isArray(r)) return { ok: false, problem: `${at} is not an object.` };
+    if (!KINDS.includes(r.kind)) {
+      return { ok: false, problem: `${at} has kind ${JSON.stringify(r.kind)} — expected one of ${KINDS.filter(Boolean).join(", ")}.` };
+    }
+    if (r.url !== undefined && r.url !== "" && !isHttpUrl(r.url)) {
+      return { ok: false, problem: `${at} has a url that is not http(s): ${JSON.stringify(r.url)}.` };
+    }
+    if (r.models !== undefined && (!Array.isArray(r.models) || !r.models.every(isStr))) {
+      return { ok: false, problem: `${at}.models must be a list of model names.` };
+    }
+    if (r.defaultModel !== undefined && !isStr(r.defaultModel)) {
+      return { ok: false, problem: `${at}.defaultModel must be text.` };
+    }
+    // "false" as a STRING is truthy — the exact trap the API's own settings writer documents.
+    if (r.enabled !== undefined && typeof r.enabled !== "boolean") {
+      return { ok: false, problem: `${at}.enabled must be true or false, not ${JSON.stringify(r.enabled)}.` };
+    }
+    const dup = `${r.kind}|${clean(r.url).toLowerCase()}`;
+    if (seen.has(dup)) return { ok: false, problem: `${at} repeats a provider already in the file (${r.kind} ${clean(r.url) || "no url"}).` };
+    seen.add(dup);
+    backends.push({
+      kind: r.kind,
+      url: clean(r.url),
+      defaultModel: clean(r.defaultModel),
+      models: (r.models ?? []).map((m) => m.trim()).filter(Boolean),
+      enabled: r.enabled !== false,
+    });
+  }
+  const am = doc.agentModel;
+  if (am !== undefined && (!am || typeof am !== "object" || Array.isArray(am))) {
+    return { ok: false, problem: "agentModel must be an object with a url and a name." };
+  }
+  if (am?.url !== undefined && am.url !== "" && !isHttpUrl(am.url)) {
+    return { ok: false, problem: `agentModel.url is not http(s): ${JSON.stringify(am.url)}.` };
+  }
+  if (am?.name !== undefined && !isStr(am.name)) {
+    return { ok: false, problem: "agentModel.name must be text." };
+  }
+  if (doc.keys !== undefined && !Array.isArray(doc.keys)) {
+    return { ok: false, problem: "keys must be a list." };
+  }
+  const keys = [];
+  for (const [i, k] of (doc.keys ?? []).entries()) {
+    const at = `keys[${i}]`;
+    if (!k || typeof k !== "object" || Array.isArray(k)) return { ok: false, problem: `${at} is not an object.` };
+    if (!clean(k.name)) return { ok: false, problem: `${at} has no name — a key is identified by its name.` };
+    if (k.key !== undefined && !isStr(k.key)) return { ok: false, problem: `${at}.key must be text.` };
+    if (k.backendUrl !== undefined && k.backendUrl !== "" && !isHttpUrl(k.backendUrl)) {
+      return { ok: false, problem: `${at}.backendUrl is not http(s): ${JSON.stringify(k.backendUrl)}.` };
+    }
+    keys.push({
+      name: clean(k.name),
+      tail: clean(k.tail),
+      ...(clean(k.backendUrl) ? { backendUrl: clean(k.backendUrl) } : {}),
+      // Present only when a person put it there by hand; gu never writes one.
+      ...(clean(k.key) ? { key: clean(k.key) } : {}),
+    });
+  }
+  return {
+    ok: true,
+    value: { backends, agentModel: { url: clean(am?.url), name: clean(am?.name) }, keys, savedAt: clean(doc.savedAt), savedOn: clean(doc.savedOn) },
+    // Loading a file someone hand-edited to carry live credentials is allowed, but it is not
+    // allowed to be quiet: that file is now a secret on disk.
+    carriesSecrets: keys.some((k) => k.key),
+  };
+}
+
+/**
+ * What loading this file would do to the machine it is loaded on.
+ *
+ * REPLACES, DOES NOT MERGE. Two providers with the same URL are the same provider, and merging
+ * would leave a machine holding both the file's idea of a provider and its own — which is how a
+ * /model list ends up with two rows that look identical and behave differently. The plan says so
+ * plainly, because "replace" is the part a person needs to agree to.
+ */
+export function planLoad(file, current = {}) {
+  const currentRows = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
+  const currentKeys = Array.isArray(current.keys) ? current.keys : [];
+  const have = new Set(currentKeys.map((k) => clean(k.name).toLowerCase()).filter(Boolean));
+  const missingKeys = file.keys.filter((k) => !have.has(k.name.toLowerCase()) && !k.key);
+  const lines = [];
+  lines.push(
+    file.backends.length
+      ? `${file.backends.length} coding provider${file.backends.length === 1 ? "" : "s"}${currentRows.length ? `, replacing the ${currentRows.length} on this account` : ""}:`
+      : "no coding providers in the file — the ones on this account stay as they are.",
+  );
+  for (const b of file.backends) {
+    const models = b.models.length ? `${b.models.length} model${b.models.length === 1 ? "" : "s"}` : "no models";
+    lines.push(`  ${b.kind || "?"}  ${b.url || "(no url)"}  ${models}${b.defaultModel ? `, default ${b.defaultModel}` : ""}${b.enabled ? "" : "  (disabled)"}`);
+  }
+  if (file.agentModel.url || file.agentModel.name) {
+    lines.push(`agent model: ${file.agentModel.name || "(server default)"}${file.agentModel.url ? ` at ${file.agentModel.url}` : ""}`);
+  }
+  if (missingKeys.length) {
+    lines.push(`${missingKeys.length} API key${missingKeys.length === 1 ? "" : "s"} this account does not have — gu will ask for ${missingKeys.length === 1 ? "it" : "them"} after:`);
+    for (const k of missingKeys) lines.push(`  ${k.name}${k.tail ? ` (…${k.tail})` : ""}${k.backendUrl ? ` for ${k.backendUrl}` : ""}`);
+  }
+  // The account default is NOT in the file and is not touched — said out loud, because someone
+  // loading "their models" onto a machine reasonably expects the coder to change too.
+  lines.push("your current coding model choice is not changed — pick one with /model.");
+  return { lines, missingKeys, replaces: currentRows.length, adds: file.backends.length };
+}
+
+/**
+ * The POST body for /api/worker/settings. Only fields a worker key may write.
+ *
+ * A PROVIDER THIS ACCOUNT ALREADY HAS KEEPS ITS ROW ID, and that is not a detail. An API key is
+ * bound to a row BY ID; a key whose row has gone is, in this codebase's own words, "ineligible
+ * everywhere AND filtered out of every picker" — it can never be selected, used or deleted again.
+ * Folder picks and job records name rows the same way. So loading a file onto a machine that
+ * already has api.openai.com must reuse that row rather than mint a second one: matched on
+ * kind + url, which is what makes two rows the same provider. Genuinely new rows carry no id and
+ * the API mints one, which is what keeps ids unique per account instead of imported from someone
+ * else's.
+ */
+export function toSettingsPatch(file, current = {}) {
+  const patch = {};
+  const existing = Array.isArray(current.agentCodingBackends) ? current.agentCodingBackends : [];
+  const idFor = (kind, url) =>
+    existing.find(
+      (r) => r?.id && r.kind === kind && clean(r.url).toLowerCase() === clean(url).toLowerCase(),
+    )?.id ?? "";
+  if (file.backends.length) {
+    patch.agentCodingBackends = file.backends.map((b) => {
+      const id = idFor(b.kind, b.url);
+      return {
+        ...(id ? { id } : {}),
+        kind: b.kind,
+        url: b.url,
+        defaultModel: b.defaultModel,
+        models: b.models,
+        enabled: b.enabled,
+      };
+    });
+  }
+  if (file.agentModel.url) patch.agentModelUrl = file.agentModel.url;
+  if (file.agentModel.name) patch.agentModelName = file.agentModel.name;
+  return patch;
+}