@jiayunxie/aerial 0.2.5 → 0.2.6

package/src/cli/select.js

@@ -0,0 +1,340 @@
+import readline from "node:readline";
+import { stdin as input, stdout as output } from "node:process";
+import { proxyModels } from "../proxy/index.js";
+import { readJsonSafely } from "../shared/utils.js";
+import { modelsForRoute } from "../proxy/models.js";
+import { codexStatus, claudeStatus } from "../setup/clients.js";
+import { DEFAULT_EFFORT, EFFORT_VALUES, assertValidEffort, normalizeEffort } from "../shared/effort.js";
+
+export { modelsForRoute } from "../proxy/models.js";
+export { DEFAULT_EFFORT, EFFORT_VALUES, normalizeEffort, assertValidEffort } from "../shared/effort.js";
+
+const MAX_LISTED_MODELS = 20;
+const GPT_VERSION_RE = /^gpt-(\d+)(?:\.(\d+))?/i;
+const STABLE_GPT_RE = /^gpt-\d+(?:\.\d+)?$/i;
+
+const CLEAR_LINE = "\x1b[2K";
+const CURSOR_UP = "\x1b[1A";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+
+const MAX_VISIBLE = 10;
+
+// Color is opt-out via NO_COLOR and gated on a real TTY, so piped output and
+// dumb terminals get clean ASCII instead of escape-code soup.
+const COLOR = process.env.NO_COLOR ? false : Boolean(output.isTTY);
+
+const sgr = (code) => (COLOR ? `\x1b[${code}m` : "");
+const RESET = sgr(0);
+const BOLD = sgr(1);
+const DIM = sgr(2);
+const CYAN = sgr(36);
+const BRIGHT_CYAN = sgr(96);
+const GREEN = sgr(32);
+const BLUE = sgr(34);
+const YELLOW = sgr(33);
+
+const GLYPHS = COLOR
+  ? { bar: "▌", on: "●", off: "○", arrow: "↑", darrow: "↓", enter: "⏎" }
+  : { bar: "|", on: "*", off: " ", arrow: "^", darrow: "v", enter: "<-" };
+
+const TAG_COLORS = {
+  recommended: GREEN,
+  current: BLUE,
+  selected: BLUE,
+  default: YELLOW
+};
+
+function paintTags(tags) {
+  if (!tags.length) return "";
+  const painted = tags.map((t) => `${TAG_COLORS[t] || DIM}${t}${RESET}`).join(`${DIM}, ${RESET}`);
+  return `  ${painted}`;
+}
+
+function helpBar() {
+  const key = (s) => `${DIM}${s}${RESET}`;
+  return `${key(`${GLYPHS.arrow}${GLYPHS.darrow}`)} move  ${key(GLYPHS.enter)} select  ${key("q")} cancel`;
+}
+
+export function viewportStart(cursor, total, maxVisible) {
+  if (total <= maxVisible) return 0;
+  const half = Math.floor(maxVisible / 2);
+  const start = cursor - half;
+  if (start < 0) return 0;
+  if (start + maxVisible > total) return total - maxVisible;
+  return start;
+}
+
+function buildFrame({ title, items, cursor, getTags, maxVisible = MAX_VISIBLE }) {
+  const lines = [`${BOLD}${title}${RESET}`, ""];
+  const total = items.length;
+  const start = viewportStart(cursor, total, maxVisible);
+  const end = Math.min(start + maxVisible, total);
+  // Overflow hints occupy a fixed line whether or not there is overflow, so the
+  // frame height stays constant and incremental redraws never leave stale rows.
+  lines.push(start > 0 ? `${DIM}   ${GLYPHS.arrow} ${start} more${RESET}` : "");
+  for (let index = start; index < end; index++) {
+    const item = items[index];
+    const active = index === cursor;
+    const tagText = paintTags(getTags ? getTags(item, index) : []);
+    if (active) {
+      const bar = `${BRIGHT_CYAN}${GLYPHS.bar}${RESET}`;
+      const dot = `${BRIGHT_CYAN}${GLYPHS.on}${RESET}`;
+      lines.push(`${bar} ${dot} ${CYAN}${BOLD}${item.label}${RESET}${tagText}`);
+    } else {
+      lines.push(`  ${DIM}${GLYPHS.off}${RESET} ${item.label}${tagText}`);
+    }
+  }
+  lines.push(end < total ? `${DIM}   ${GLYPHS.darrow} ${total - end} more${RESET}` : "");
+  lines.push("");
+  lines.push(helpBar());
+  return lines;
+}
+
+/**
+ * Arrow-key list selector. TTY-only; callers gate on isTTY and supply their own
+ * non-interactive path. Number keys jump to that 1-based row and Enter confirms,
+ * so tests can drive it by feeding "3\n".
+ */
+async function select({
+  title,
+  items,
+  initialIndex = 0,
+  getTags,
+  maxVisible = MAX_VISIBLE,
+  input: inputStream = input,
+  output: outputStream = output
+} = {}) {
+  if (!items.length) throw new Error("select requires at least one item");
+  let cursor = Math.min(Math.max(initialIndex, 0), items.length - 1);
+  let drawn = 0;
+
+  const render = () => {
+    if (drawn) outputStream.write(CURSOR_UP.repeat(drawn - 1) + "\r");
+    const lines = buildFrame({ title, items, cursor, getTags, maxVisible });
+    outputStream.write(lines.map((line) => CLEAR_LINE + line).join("\n"));
+    drawn = lines.length;
+  };
+
+  const wasRaw = Boolean(inputStream.isRaw);
+  const wasPaused = inputStream.isPaused();
+  readline.emitKeypressEvents(inputStream);
+  if (inputStream.isTTY && inputStream.setRawMode) inputStream.setRawMode(true);
+  inputStream.resume();
+  outputStream.write(HIDE_CURSOR);
+  render();
+
+  return await new Promise((resolve) => {
+    const cleanup = () => {
+      inputStream.removeListener("keypress", onKeypress);
+      if (inputStream.isTTY && inputStream.setRawMode) inputStream.setRawMode(wasRaw);
+      // Restore stdin to its prior flow state. emitKeypressEvents/resume left it
+      // flowing; if it started paused (the usual CLI case), re-pausing lets the
+      // event loop drain so the process exits after the final selection — while
+      // still allowing a subsequent select() in the same run to resume cleanly.
+      if (wasPaused) inputStream.pause();
+      outputStream.write("\n" + SHOW_CURSOR);
+    };
+    const onKeypress = (str, key) => {
+      if (!key) return;
+      if (key.name === "up" || key.name === "k") {
+        cursor = (cursor - 1 + items.length) % items.length;
+        render();
+      } else if (key.name === "down" || key.name === "j") {
+        cursor = (cursor + 1) % items.length;
+        render();
+      } else if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        resolve({ index: cursor, item: items[cursor], cancelled: false });
+      } else if (key.name === "q" || key.name === "escape" || (key.ctrl && key.name === "c")) {
+        cleanup();
+        resolve({ index: cursor, item: items[cursor], cancelled: true });
+      } else if (/^[1-9]$/.test(str || "")) {
+        const target = Number(str) - 1;
+        if (target < items.length) {
+          cursor = target;
+          render();
+        }
+      }
+    };
+    inputStream.on("keypress", onKeypress);
+  });
+}
+
+function gptVersionScore(id) {
+  const match = GPT_VERSION_RE.exec(id);
+  if (!match) return undefined;
+  const major = Number(match[1]);
+  const minor = match[2] === undefined ? 0 : Number(match[2]);
+  return major * 1000 + minor;
+}
+
+export function rankModels(choices) {
+  return [...choices]
+    .map((choice, index) => ({ choice, index, score: gptVersionScore(choice.id) }))
+    .sort((a, b) => {
+      if (a.score !== undefined && b.score !== undefined && a.score !== b.score) return b.score - a.score;
+      if (a.score !== undefined && b.score === undefined) return -1;
+      if (a.score === undefined && b.score !== undefined) return 1;
+      return a.index - b.index;
+    })
+    .map((entry) => entry.choice);
+}
+
+export function pickRecommended(choices) {
+  if (!choices.length) return { recommended: undefined, source: "first_available" };
+  const ranked = rankModels(choices);
+  const stable = ranked.filter((c) => STABLE_GPT_RE.test(c.id));
+  if (stable.length) return { recommended: stable[0].id, source: "recommended_stable", ranked };
+  return { recommended: ranked[0].id, source: "recommended_fallback", ranked };
+}
+
+export function orderForPrompt(ranked, recommended) {
+  if (!recommended) return [...ranked];
+  const found = ranked.find((c) => c.id === recommended);
+  if (!found) return [...ranked];
+  return [found, ...ranked.filter((c) => c.id !== recommended)];
+}
+
+export async function discoverModelsForRoute(route) {
+  const response = await proxyModels(new Request("http://aerial.local/v1/models", { method: "GET" }));
+  const payload = await readJsonSafely(response);
+  if (!response.ok) {
+    const detail = payload.error || payload.raw || JSON.stringify(payload);
+    throw new Error(`Could not load Copilot models (${response.status}): ${detail}`);
+  }
+  const models = Array.isArray(payload.data) ? payload.data : [];
+  return modelsForRoute(models, route);
+}
+
+function currentModelFor(target) {
+  try {
+    const status = target === "Codex" ? codexStatus() : claudeStatus();
+    return typeof status.model === "string" ? status.model : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function currentEffortFor(target) {
+  try {
+    const status = target === "Codex" ? codexStatus() : claudeStatus();
+    return typeof status.effort === "string" ? normalizeEffort(status.effort) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function chooseSetupModel({
+  target,
+  route,
+  explicitModel,
+  prompt,
+  input: inputStream = input,
+  output: outputStream = output
+} = {}) {
+  if (explicitModel) return { model: explicitModel, choices: [], source: "explicit" };
+  let raw;
+  try {
+    raw = await discoverModelsForRoute(route);
+  } catch (err) {
+    throw new Error(`${err.message}\nRun \`aerial login\` first, or pass \`--model <id>\` if you already know which ${target} model to use.`);
+  }
+  if (!raw.length) {
+    throw new Error(`No Copilot models currently advertise the ${route} route needed by ${target}. Run \`aerial probe\` to inspect the full model list.`);
+  }
+  const { recommended, source: recommendedSource, ranked } = pickRecommended(raw);
+  const choices = ranked;
+  const promptListed = orderForPrompt(ranked, recommended);
+  const shouldPrompt = prompt === undefined ? Boolean(inputStream.isTTY) : prompt;
+  if (!shouldPrompt) return { model: recommended, choices, source: recommendedSource, recommended };
+
+  const current = currentModelFor(target);
+  const items = promptListed.map((choice) => ({ label: choice.id, id: choice.id }));
+  const currentIndex = items.findIndex((item) => item.id === current);
+  const initialIndex = currentIndex >= 0 ? currentIndex : 0;
+
+  outputStream.write(`Available ${target} models (${route} route):\n`);
+  if (recommendedSource === "recommended_fallback") {
+    outputStream.write(`  No stable gpt-N.M model available; ${recommended} is the fallback. Pass --model <id> to override.\n`);
+  }
+
+  const { item, cancelled } = await select({
+    title: `Choose ${target} model:`,
+    items,
+    initialIndex,
+    getTags: (it) => {
+      const tags = [];
+      if (it.id === recommended) tags.push("recommended");
+      if (it.id === current) tags.push("current");
+      return tags;
+    },
+    input: inputStream,
+    output: outputStream
+  });
+  if (cancelled) throw new Error(`${target} setup cancelled.`);
+  return { model: item.id, choices, source: "prompt", displayed: true, recommended };
+}
+
+export function formatModelChoices({ target, route, choices, selectedModel, source, recommended }) {
+  if (!choices.length) return [];
+  const lines = [
+    `Available ${target} models (${route} route):`
+  ];
+  for (const [index, choice] of choices.slice(0, MAX_LISTED_MODELS).entries()) {
+    const markers = [];
+    if (choice.id === recommended) markers.push("recommended");
+    if (choice.id === selectedModel) markers.push("selected");
+    const suffix = markers.length ? `  (${markers.join(", ")})` : "";
+    lines.push(`  ${index + 1}. ${choice.id}${suffix}`);
+  }
+  if (choices.length > MAX_LISTED_MODELS) lines.push(`  ... ${choices.length - MAX_LISTED_MODELS} more`);
+  if (source === "first_available" || source === "recommended_stable") {
+    lines.push(`No interactive terminal detected; selected ${selectedModel}. Pass --model <id> to choose a different model.`);
+  } else if (source === "recommended_fallback") {
+    lines.push(`No stable gpt-N.M model available; selected ${selectedModel}. Pass --model <id> to override.`);
+  } else {
+    lines.push(`Selected ${target} model: ${selectedModel}`);
+  }
+  return lines;
+}
+
+export async function chooseSetupEffort({
+  target,
+  explicitEffort,
+  prompt,
+  input: inputStream = input,
+  output: outputStream = output
+} = {}) {
+  if (explicitEffort !== undefined) {
+    return { effort: assertValidEffort(explicitEffort), source: "explicit", displayed: false };
+  }
+  const shouldPrompt = prompt === undefined ? Boolean(inputStream.isTTY) : prompt;
+  if (!shouldPrompt) {
+    return { effort: DEFAULT_EFFORT, source: "default_non_tty", displayed: false };
+  }
+  const current = currentEffortFor(target);
+  const currentIndex = EFFORT_VALUES.indexOf(current);
+  const initialIndex = currentIndex >= 0 ? currentIndex : EFFORT_VALUES.indexOf(DEFAULT_EFFORT);
+  const { item, cancelled } = await select({
+    title: `Choose ${target} reasoning effort:`,
+    items: EFFORT_VALUES.map((value) => ({ label: value, value })),
+    initialIndex,
+    getTags: (it) => {
+      const tags = [];
+      if (it.value === DEFAULT_EFFORT) tags.push("default");
+      if (it.value === current) tags.push("current");
+      return tags;
+    },
+    input: inputStream,
+    output: outputStream
+  });
+  if (cancelled) throw new Error(`${target} setup cancelled.`);
+  return { effort: item.value, source: "prompt", displayed: true };
+}
+
+export function formatEffortSelection({ target, effort, source }) {
+  if (source === "explicit") return `Selected ${target} effort: ${effort}`;
+  if (source === "prompt") return `Selected ${target} effort: ${effort}`;
+  return `No interactive terminal detected; selected ${target} effort: ${effort}. Pass --effort <low|medium|high|xhigh|max> to choose a different effort.`;
+}

package/src/proxy/models.js

@@ -27,3 +27,24 @@ export async function annotateModelsResponse(response) {
     data: payload.data.map((model) => ({ ...model, aerial: aerialSupportForModel(model) }))
   }, { status: response.status, headers: copyResponseHeaders(response) });
 }
+
+export function aerialRoutes(model) {
+  return Array.isArray(model?.aerial?.routes) ? model.aerial.routes : [];
+}
+
+export function modelsForRoute(models, route) {
+  return models
+    .filter((model) => typeof model?.id === "string" && aerialRoutes(model).includes(route))
+    .map((model) => ({ id: model.id, routes: aerialRoutes(model), notes: model.aerial?.notes || [] }));
+}
+
+export function usageSummary(payload) {
+  const usage = payload?.usage || payload?.response?.usage || {};
+  return {
+    input: usage.input_tokens ?? usage.prompt_tokens,
+    output: usage.output_tokens ?? usage.completion_tokens,
+    cached: usage.input_tokens_details?.cached_tokens
+      ?? usage.prompt_tokens_details?.cached_tokens
+      ?? usage.cache_read_input_tokens
+  };
+}

package/src/service/platform.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { loadConfig } from "../shared/config.js";
 import { logEvent } from "../shared/log.js";
-import { atomicWriteFile } from "../shared/file-utils.js";
+import { atomicWriteFile } from "../shared/utils.js";
 import {
   SERVICE_LABEL,
   WIN_TASK_NAME,

package/src/setup/clients.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { ensureApiKey, loadConfig, saveConfig } from "../shared/config.js";
 import { logEvent } from "../shared/log.js";
-import { atomicWriteFile } from "../shared/file-utils.js";
+import { atomicWriteFile } from "../shared/utils.js";
 import { assertValidEffort, normalizeEffort } from "../shared/effort.js";
-import { backupIfExists, backupPathsFor } from "./backup.js";
-import { setTomlRootString, upsertTomlSection } from "./toml.js";
+import { backupIfExists, backupPathsFor } from "./restore.js";
+import { setTomlRootString, upsertTomlSection, removeTomlSection } from "./toml.js";
 
 const DEFAULT_CODEX_AUTH = Object.freeze({
   command: "aerial",
@@ -51,6 +51,7 @@ export function setupCodex({ model, effort, authCommand = DEFAULT_CODEX_AUTH } =
   let content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
   content = setTomlRootString(content, "model_provider", "aerial");
   content = setTomlRootString(content, "model", selectedModel);
+  if (normalizedEffort) content = setTomlRootString(content, "model_reasoning_effort", normalizedEffort);
   content = upsertTomlSection(content, "model_providers.aerial", {
     name: "Aerial",
     base_url: `http://${config.host}:${config.port}/v1`,
@@ -62,9 +63,7 @@ export function setupCodex({ model, effort, authCommand = DEFAULT_CODEX_AUTH } =
     timeout_ms: authCommand.timeout_ms || DEFAULT_CODEX_AUTH.timeout_ms,
     refresh_interval_ms: authCommand.refresh_interval_ms ?? DEFAULT_CODEX_AUTH.refresh_interval_ms
   });
-  const profileValues = { model_provider: "aerial", model: selectedModel };
-  if (normalizedEffort) profileValues.model_reasoning_effort = normalizedEffort;
-  content = upsertTomlSection(content, "profiles.aerial", profileValues);
+  content = removeTomlSection(content, "profiles.aerial");
   atomicWriteFile(file, content);
   if (normalizedEffort && config.defaultEffort !== normalizedEffort) {
     saveConfig({ ...config, defaultEffort: normalizedEffort });
@@ -146,9 +145,23 @@ export function codexStatus() {
   const baseUrl = typeof doc?.model_providers?.aerial?.base_url === "string"
     ? doc.model_providers.aerial.base_url
     : undefined;
-  const profileEffort = doc?.profiles?.aerial?.model_reasoning_effort;
-  const effort = typeof profileEffort === "string" ? (normalizeEffort(profileEffort) || "missing") : "missing";
-  return { target: "codex", state, file, backups, model, baseUrl, effort };
+  const rootEffort = doc?.model_reasoning_effort;
+  const effort = typeof rootEffort === "string" ? (normalizeEffort(rootEffort) || "missing") : "missing";
+  const legacyProfile = doc?.profiles?.aerial && typeof doc.profiles.aerial === "object";
+  const legacyProfileLooksAerial = legacyProfile
+    && (doc.profiles.aerial.model_provider === "aerial"
+      || typeof doc.profiles.aerial.model_reasoning_effort === "string");
+  const needsMigration = legacyProfile && (state !== "not-aerial" || legacyProfileLooksAerial);
+  return {
+    target: "codex",
+    state,
+    file,
+    backups,
+    model,
+    baseUrl,
+    effort,
+    ...(needsMigration ? { migration: "run aerial setup codex" } : {})
+  };
 }
 
 function claudeStateFromDoc(doc, expectedBaseUrl) {

package/src/setup/index.js

@@ -1,4 +1,27 @@
-export { findLatestBackup } from "./backup.js";
+import fs from "node:fs";
+import { loadConfig } from "../shared/config.js";
+import { apiKeyPath, githubTokenPath } from "../shared/paths.js";
+import { gitHubTokenSource } from "../shared/auth.js";
+import { CLIENTS, setupCodex, setupClaude, codexStatus, claudeStatus } from "./clients.js";
+
 export { setupCodex, setupClaude, codexStatus, claudeStatus } from "./clients.js";
-export { setupStatus } from "./status.js";
-export { restoreClient, restoreAllClients } from "./restore.js";
+export { findLatestBackup, restoreClient, restoreAllClients } from "./restore.js";
+
+export function setupStatus() {
+  const config = loadConfig();
+  const apiKeyFile = apiKeyPath();
+  const githubTokenFile = githubTokenPath();
+  return {
+    schema: "aerial.setup-status.v1",
+    platform: process.platform,
+    config: { host: config.host, port: config.port },
+    auth: {
+      api_key: { file: apiKeyFile, exists: fs.existsSync(apiKeyFile) },
+      github_token: (() => {
+        const source = gitHubTokenSource();
+        return { file: githubTokenFile, exists: source !== "missing", source };
+      })()
+    },
+    clients: Object.fromEntries(Object.entries(CLIENTS).map(([target, client]) => [target, client.status()]))
+  };
+}

package/src/setup/restore.js

@@ -1,9 +1,45 @@
 import fs from "node:fs";
+import path from "node:path";
 import { logEvent } from "../shared/log.js";
-import { atomicWriteFile } from "../shared/file-utils.js";
-import { findLatestBackup } from "./backup.js";
+import { atomicWriteFile } from "../shared/utils.js";
 import { CLIENTS } from "./clients.js";
 
+const BACKUP_PREFIX = ".aerial-backup-";
+const ISO_STAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+
+export function backupIfExists(file) {
+  if (!fs.existsSync(file)) return undefined;
+  const backup = `${file}.aerial-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  fs.copyFileSync(file, backup);
+  return backup;
+}
+
+function listBackups(file) {
+  const dir = path.dirname(file);
+  const base = path.basename(file);
+  if (!fs.existsSync(dir)) return [];
+  const prefix = `${base}${BACKUP_PREFIX}`;
+  const entries = fs.readdirSync(dir);
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix)) continue;
+    const stamp = entry.slice(prefix.length);
+    if (!ISO_STAMP_RE.test(stamp)) continue;
+    matches.push({ name: entry, path: path.join(dir, entry), stamp });
+  }
+  matches.sort((a, b) => (a.stamp < b.stamp ? -1 : a.stamp > b.stamp ? 1 : 0));
+  return matches;
+}
+
+export function findLatestBackup(file) {
+  const all = listBackups(file);
+  return all.length ? all[all.length - 1] : undefined;
+}
+
+export function backupPathsFor(file) {
+  return listBackups(file).map((entry) => entry.path);
+}
+
 const PRE_RESTORE_PREFIX = ".aerial-pre-restore-";
 
 function clientDescriptor(target) {

package/src/setup/toml.js

@@ -1,41 +1,92 @@
-function tomlValue(value) {
-  if (Array.isArray(value)) return `[${value.map(tomlValue).join(", ")}]`;
-  if (typeof value === "number" || typeof value === "boolean") return String(value);
-  return JSON.stringify(String(value));
-}
+import { stringify as stringifyToml } from "smol-toml";
 
 function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function tomlScalar(value) {
+  return stringifyToml({ value }).trim().replace(/^value\s*=\s*/, "");
+}
+
+function serializeBlock(values) {
+  const text = stringifyToml(values).trimEnd();
+  return text ? text.split("\n") : [];
+}
+
+function sectionName(line) {
+  const match = /^\s*\[\[?(.+?)\]?\]\s*(?:#.*)?$/.exec(line);
+  if (!match) return undefined;
+  const inner = match[1].trim();
+  if (!inner) return undefined;
+  const segment = `(?:"[^"]*"|'[^']*'|[A-Za-z0-9_-]+)`;
+  return new RegExp(`^${segment}(?:\\s*\\.\\s*${segment})*$`).test(inner) ? inner : undefined;
+}
+
+function isSectionHeader(line) {
+  return sectionName(line) !== undefined;
+}
+
+function isSectionOrChild(line, section) {
+  const name = sectionName(line);
+  return name === section || name?.startsWith(`${section}.`);
+}
+
 export function setTomlRootString(content, key, value) {
-  const line = `${key} = ${tomlValue(value)}`;
+  const line = `${key} = ${tomlScalar(value)}`;
   const source = content.split(/\r?\n/);
-  const firstSection = source.findIndex((sourceLine) => /^\s*\[.*\]\s*(?:#.*)?$/.test(sourceLine));
+  const firstSection = source.findIndex(isSectionHeader);
   const rootLines = firstSection === -1 ? source : source.slice(0, firstSection);
   const restLines = firstSection === -1 ? [] : source.slice(firstSection);
-  const root = rootLines.join("\n");
-  const rest = restLines.join("\n");
-  const re = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=.*$`, "m");
-  const nextRoot = re.test(root) ? root.replace(re, line) : `${root.trimEnd()}${root.trimEnd() ? "\n" : ""}${line}`;
-  if (!rest) return `${nextRoot.trimEnd()}\n`;
-  return `${nextRoot.trimEnd()}\n${rest}`;
+  const re = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  const existing = rootLines.findIndex((rootLine) => re.test(rootLine));
+  if (existing === -1) {
+    let insertAt = rootLines.length;
+    while (insertAt > 0 && !rootLines[insertAt - 1].trim()) insertAt -= 1;
+    rootLines.splice(insertAt, 0, line);
+  } else {
+    rootLines[existing] = line;
+  }
+  const merged = [...rootLines, ...restLines].join("\n");
+  return `${merged.trimEnd()}\n`;
 }
 
 export function upsertTomlSection(content, section, values) {
   const heading = `[${section}]`;
-  const lines = Object.entries(values).map(([key, value]) => `${key} = ${tomlValue(value)}`).join("\n");
-  const block = `${heading}\n${lines}\n`;
+  const block = [heading, ...serializeBlock(values)];
   const source = content.split(/\r?\n/);
-  const start = source.findIndex((line) => line.trim() === heading);
-  if (start === -1) return `${content.trimEnd()}\n\n${block}`;
+  const start = source.findIndex((line) => sectionName(line) === section);
+  if (start === -1) {
+    const base = content.trimEnd();
+    return `${base ? `${base}\n\n` : ""}${block.join("\n")}\n`;
+  }
   let end = source.length;
   for (let i = start + 1; i < source.length; i += 1) {
-    if (/^\s*\[.*\]\s*$/.test(source[i])) {
+    if (isSectionHeader(source[i])) {
       end = i;
       break;
     }
   }
-  source.splice(start, end - start, ...block.trimEnd().split("\n"));
+  while (end > start + 1 && !source[end - 1].trim()) end -= 1;
+  source.splice(start, end - start, ...block);
   return `${source.join("\n").trimEnd()}\n`;
 }
+
+export function removeTomlSection(content, section) {
+  const source = content.split(/\r?\n/);
+  const kept = [];
+  let removed = false;
+  for (let i = 0; i < source.length;) {
+    if (isSectionOrChild(source[i], section)) {
+      removed = true;
+      i += 1;
+      while (i < source.length && !isSectionHeader(source[i])) i += 1;
+      while (i < source.length && !source[i].trim()) i += 1;
+    } else {
+      kept.push(source[i]);
+      i += 1;
+    }
+  }
+  if (!removed) return content.trim() ? `${content.trimEnd()}\n` : "";
+  const merged = kept.join("\n").trim();
+  return merged ? `${merged}\n` : "";
+}

package/src/shared/paths.js

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs";
-import { atomicWriteFile } from "./file-utils.js";
+import { atomicWriteFile } from "./utils.js";
 
 export function configDir() {
   if (process.env.AERIAL_CONFIG_DIR) return process.env.AERIAL_CONFIG_DIR;

package/src/shared/{file-utils.js → utils.js}

@@ -1,6 +1,25 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export function parseNumberChoice(value, { max, defaultIndex = 0, oneBased = false } = {}) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) return defaultIndex;
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const n = Number(trimmed);
+  if (n < 1 || n > max) return undefined;
+  return oneBased ? n : n - 1;
+}
+
+export async function readJsonSafely(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
 function ensureParentDir(file) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
 }