@jiayunxie/aerial 0.2.5 → 0.2.6

package/README.md

@@ -122,7 +122,7 @@ aerial status           # setup, login, service, and health summary
 aerial proxy status     # upstream proxy mode, egress, and route visibility
 aerial service install  # install and start the background service
 aerial doctor           # local diagnostics
-aerial disable          # restore client configs and uninstall the service
+aerial teardown          # restore client configs and uninstall the service
 ```
 
 `aerial start` is for foreground debugging in the current terminal. Most users should use `aerial service install`.
@@ -136,7 +136,7 @@ Advanced service lifecycle commands are documented in `docs/usage.md`.
 - No models listed during setup: run `aerial login` first, then retry setup.
 - Claude models or the `messages` route are missing: run `aerial proxy enable`, then `aerial probe`.
 - Port conflict on `18181`: run `aerial status` to see whether another process is using the port.
-- Need to undo setup: run `aerial disable`, or restore one client with `aerial setup restore <codex|claude> --latest`.
+- Need to undo setup: run `aerial teardown`, or restore one client with `aerial setup restore <codex|claude> --latest`.
 
 ## Notes
 

package/docs/usage.md

@@ -91,7 +91,7 @@ The local key is generated and stored by Aerial automatically. Users do not need
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
-To skip the prompts, pass `--model <responses-model-id>` and/or `--effort <low|medium|high|xhigh|max>` (`max` is an alias for `xhigh`). The chosen effort is written into the `[profiles.aerial]` block as `model_reasoning_effort = "<effort>"` and is also persisted as Aerial-wide `defaultEffort` in `~/.aerial/config.json`. Under non-TTY (CI/pipes) the wizard does not prompt and falls back to the default effort `medium`.
+To skip the prompts, pass `--model <responses-model-id>` and/or `--effort <low|medium|high|xhigh|max>` (`max` is an alias for `xhigh`). The chosen effort is written as root-level `model_reasoning_effort = "<effort>"` and is also persisted as Aerial-wide `defaultEffort` in `~/.aerial/config.json`. Under non-TTY (CI/pipes) the wizard does not prompt and falls back to the default effort `medium`.
 
 ## 6. Configure Claude Code
 
@@ -171,7 +171,7 @@ Use `responses` models for Codex, `messages` models for Claude Code, and `chat`
 ```bash
 aerial setup status [--json]
 aerial setup restore <codex|claude|all> --latest
-aerial disable
+aerial teardown
 ```
 
 `aerial setup status` reports whether each supported client is currently configured to route through Aerial, plus the local API key and GitHub token files. The state for each client is one of:
@@ -221,7 +221,7 @@ Stability rules for `aerial.setup-status.v1`: new fields may be added at any lev
 
 `aerial setup restore <codex|claude|all> --latest` restores the most recent `*.aerial-backup-<ISO>` snapshot for the named client. Before overwriting, it takes a `*.aerial-pre-restore-<ISO>` snapshot of the current file so the restore itself is reversible. With `all`, both clients are restored best-effort and the command exits non-zero if any individual restore failed. If there is no backup to restore, the command prints a note and exits 0.
 
-`aerial disable` first runs `setup restore all --latest` and then, only if every client restore succeeded, uninstalls the local Aerial service via `aerial service uninstall`. If any client restore reports a failure, the service is left running and `aerial disable` exits non-zero; resolve the restore errors, then rerun `aerial disable` (or call `aerial service uninstall` directly once the client config is in the state you want).
+`aerial teardown` first runs `setup restore all --latest` and then, only if every client restore succeeded, uninstalls the local Aerial service via `aerial service uninstall`. If any client restore reports a failure, the service is left running and `aerial teardown` exits non-zero; resolve the restore errors, then rerun `aerial teardown` (or call `aerial service uninstall` directly once the client config is in the state you want).
 
 ## 7.6 Run Aerial As A Local Service
 
@@ -252,7 +252,7 @@ Wrapper env values are baked in at install time. If you set `AERIAL_LOG_MAX_BYTE
 4. If the port answers as Aerial AND the local service manager does NOT report the unit/task loaded → the definition is regenerated, but the service is NOT started. Exit 1 with `reason=foreground_running`, `definitionUpdated=true`, and an actionable next step: stop the foreground process, then run `aerial service start`. This guarantees `install` never causes two Aerial instances to fight for the port.
 5. Otherwise (port absent) → write the definition, then start the service (`launchctl bootstrap` on macOS, `schtasks /Run` on Windows). Exit 0.
 
-`aerial service start` enforces a similar shape: it refuses with `reason=not_installed` and exit 1 if the unit/task does not exist; it refuses with `reason=port_conflict` and exit 1 if a non-Aerial process owns the port; it refuses with `reason=foreground_running` and exit 1 if Aerial is already running in the foreground (not via the service manager); it returns idempotent success with `note=already running (service-managed)` if the service is already up; otherwise it starts the service. `aerial service stop` is idempotent (exit 0 + `note` when nothing is installed or nothing is running). `aerial service uninstall` is idempotent on the "no service installed" branch, but does NOT swallow real teardown failures: on macOS, if the service is loaded and `launchctl bootout` returns non-zero, the plist and wrapper are preserved and the command exits 1 with `reason=bootout_failed`; on Windows, if `schtasks /Delete` returns non-zero, the wrapper is preserved and the command exits 1 with `reason=delete_failed`. In both cases the message includes a retry pointer. `aerial service restart` blocks the start step when the stop step fails: if `stop` returns `ok=false`, the response includes `reason=stop_failed` and `start` is not attempted. `aerial disable` follows the same contract: it restores client configs first, then calls `serviceUninstall`. Only an `unsupported platform` exception is treated as a silent skip (Linux); any supported-platform uninstall failure (`ok=false` or non-`unsupported-platform` throw) propagates as exit 1 with a retry pointer at `aerial service uninstall`.
+`aerial service start` enforces a similar shape: it refuses with `reason=not_installed` and exit 1 if the unit/task does not exist; it refuses with `reason=port_conflict` and exit 1 if a non-Aerial process owns the port; it refuses with `reason=foreground_running` and exit 1 if Aerial is already running in the foreground (not via the service manager); it returns idempotent success with `note=already running (service-managed)` if the service is already up; otherwise it starts the service. `aerial service stop` is idempotent (exit 0 + `note` when nothing is installed or nothing is running). `aerial service uninstall` is idempotent on the "no service installed" branch, but does NOT swallow real teardown failures: on macOS, if the service is loaded and `launchctl bootout` returns non-zero, the plist and wrapper are preserved and the command exits 1 with `reason=bootout_failed`; on Windows, if `schtasks /Delete` returns non-zero, the wrapper is preserved and the command exits 1 with `reason=delete_failed`. In both cases the message includes a retry pointer. `aerial service restart` blocks the start step when the stop step fails: if `stop` returns `ok=false`, the response includes `reason=stop_failed` and `start` is not attempted. `aerial teardown` follows the same contract: it restores client configs first, then calls `serviceUninstall`. Only an `unsupported platform` exception is treated as a silent skip (Linux); any supported-platform uninstall failure (`ok=false` or non-`unsupported-platform` throw) propagates as exit 1 with a retry pointer at `aerial service uninstall`.
 
 If GitHub login is not yet configured, install and start still succeed (when reachable) and emit a structured warning pointing at `aerial login`; inference proxy requests return 503 until you log in, while `GET /v1/models` returns 401 with `error.aerial.status = "login_required"`. After rotating the local API key or moving the config directory, restart the service with `aerial service restart` so the new credentials are picked up.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Local GitHub Copilot proxy for Codex CLI and Claude Code with smart HTTP(S)/SOCKS5 upstream proxy support.",
   "type": "module",
   "private": false,

package/src/cli/commands/config.js

@@ -1,7 +1,7 @@
 import { defaultConfig, loadConfig, saveConfig } from "../../shared/config.js";
 import { configPath } from "../../shared/paths.js";
 import { assertValidEffort } from "../../shared/effort.js";
-import { parseConfigHost, parseConfigPort } from "../args.js";
+import { parseConfigHost, parseConfigPort } from "../helpers.js";
 
 export function runConfigCli(subcommand, rest) {
   if (subcommand === "reset") {

package/src/cli/commands/setup.js

@@ -1,10 +1,8 @@
 import { loadConfig } from "../../shared/config.js";
 import { configPath } from "../../shared/paths.js";
 import { restoreAllClients, restoreClient, setupClaude, setupCodex, setupStatus } from "../../setup/index.js";
-import { chooseSetupModel, formatModelChoices } from "../model-selection.js";
-import { assertValidEffort, chooseSetupEffort, formatEffortSelection } from "../setup-selection.js";
-import { requiredArgValue } from "../args.js";
-import { claudeApiKeyHelper, codexAuthCommand } from "../runtime-auth.js";
+import { chooseSetupModel, formatModelChoices, assertValidEffort, chooseSetupEffort, formatEffortSelection } from "../select.js";
+import { requiredArgValue, claudeApiKeyHelper, codexAuthCommand } from "../helpers.js";
 import { printRestoreResults, printSetupCompletionSummary } from "../output.js";
 
 async function selectSetupOptions(target, route, args) {
@@ -45,6 +43,7 @@ function printSetupStatus(status) {
     console.log(`${head}${effortText}  file=${cs.file}`);
     if (cs.backups.length) console.log(`         backups=${cs.backups.length}`);
     if (cs.error) console.log(`         error=${cs.error}`);
+    if (cs.migration) console.log(`         migration=${cs.migration}`);
   }
 }
 

package/src/cli/commands/start.js

@@ -1,6 +1,6 @@
 import { ensureApiKey, loadConfig } from "../../shared/config.js";
 import { startServer } from "../../proxy/server.js";
-import { argValue } from "../args.js";
+import { argValue } from "../helpers.js";
 
 export function runStartCli(args) {
   const config = loadConfig();

package/src/cli/commands/status.js

@@ -1,6 +1,6 @@
 import { setupStatus } from "../../setup/index.js";
 import { serviceStatus } from "../../service/index.js";
-import { computeAppStatus } from "../app-status.js";
+import { computeAppStatus } from "../helpers.js";
 import { printServiceSummary, printSetupSummary } from "../output.js";
 
 export async function appStatus({ json = false } = {}) {

package/src/cli/commands/{disable.js → teardown.js}

@@ -3,11 +3,11 @@ import { serviceUninstall } from "../../service/index.js";
 import { printRestoreResults } from "../output.js";
 import { printServiceUninstallResult } from "./service.js";
 
-export function runDisableCli() {
+export function runTeardownCli() {
   const { ok: restoreOk, results } = restoreAllClients();
   printRestoreResults(results);
   if (!restoreOk) {
-    console.log("service uninstall: skipped because client restore reported failures; resolve restore errors then rerun `aerial disable` or `aerial service uninstall`.");
+    console.log("service uninstall: skipped because client restore reported failures; resolve restore errors then rerun `aerial teardown` or `aerial service uninstall`.");
     process.exitCode = 1;
     return;
   }

package/src/cli/doctor.js

@@ -1,6 +1,6 @@
 import { setupStatus } from "../setup/index.js";
 import { serviceStatus } from "../service/index.js";
-import { computeAppStatus } from "./app-status.js";
+import { computeAppStatus } from "./helpers.js";
 import { readConfigFileStatus } from "../shared/config.js";
 
 const REPAIRS = Object.freeze({

package/src/cli/helpers.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_JSON_URL = new URL("../../package.json", import.meta.url);
+const CLI_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+
+export function readPackageVersion(packageJsonUrl = PACKAGE_JSON_URL) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonUrl, "utf8"));
+    if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+    throw new Error("missing version field");
+  } catch (error) {
+    const reason = error?.message || String(error);
+    console.warn(`aerial: cannot read package version (${reason}); reporting "unknown"`);
+    return "unknown";
+  }
+}
+
+export function printVersion(packageJsonUrl = PACKAGE_JSON_URL) {
+  console.log(readPackageVersion(packageJsonUrl));
+}
+
+export function argValue(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+export function requiredArgValue(args, name) {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return value;
+}
+
+export function parseConfigPort(value) {
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) throw new Error("port must be an integer between 1 and 65535");
+  const port = Number(text);
+  if (port < 1 || port > 65535) throw new Error("port must be an integer between 1 and 65535");
+  return port;
+}
+
+export function parseConfigHost(value) {
+  const host = String(value).trim().toLowerCase();
+  if (host === "127.0.0.1" || host === "localhost" || host === "::1") return host;
+  throw new Error("host must be a loopback address: 127.0.0.1, localhost, or ::1");
+}
+
+export function codexAuthCommand() {
+  return {
+    command: process.execPath,
+    args: [CLI_ENTRY, "key", "print"],
+    timeout_ms: 5000,
+    refresh_interval_ms: 0
+  };
+}
+
+function quoteCommandPart(value) {
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+export function claudeApiKeyHelper() {
+  return [process.execPath, CLI_ENTRY, "key", "print"].map(quoteCommandPart).join(" ");
+}
+
+export function computeAppStatus(setup, service) {
+  const githubTokenPresent = setup.auth.github_token.source !== "missing";
+  const apiKeyPresent = setup.auth.api_key.exists;
+  const hasAerialClient = setup.clients.codex.state === "aerial" || setup.clients.claude.state === "aerial";
+  const serviceHealthy = service.supported !== false && service.health?.aerial === true;
+  const ok = apiKeyPresent && githubTokenPresent && hasAerialClient && serviceHealthy;
+  const nextSteps = [];
+  const hints = [];
+  if (!githubTokenPresent) nextSteps.push("run: aerial login");
+  if (!hasAerialClient) nextSteps.push("run: aerial setup codex or aerial setup claude");
+  if (hasAerialClient && !apiKeyPresent) nextSteps.push("run: aerial setup codex or aerial setup claude to recreate the local Aerial key");
+  if (service.supported !== false && !service.service?.loaded) {
+    if (serviceHealthy) {
+      hints.push("Aerial is running in the foreground but no background service is installed; run `aerial service install` so it starts on reboot.");
+    } else {
+      nextSteps.push("run: aerial service install");
+    }
+  }
+  if (setup.auth.github_token.source === "env") {
+    hints.push("AERIAL_GITHUB_TOKEN is set for this process only; run aerial login without that env var to persist a service-readable login.");
+  }
+  return { schema: "aerial.status.v1", ok, setup, service, nextSteps, hints };
+}

package/src/cli/index.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import { printVersion } from "./version.js";
-import { printHelp } from "./help.js";
+import { printVersion } from "./helpers.js";
 import { appStatus } from "./commands/status.js";
 import { runConfigCli } from "./commands/config.js";
-import { runDisableCli } from "./commands/disable.js";
+import { runTeardownCli } from "./commands/teardown.js";
 import { runKeyCli } from "./commands/key.js";
 import { runLoginCli } from "./commands/login.js";
 import { runProxyCli } from "./commands/proxy.js";
@@ -13,6 +12,30 @@ import { runStartCli } from "./commands/start.js";
 import { doctor, renderDoctorText } from "./doctor.js";
 import { formatProbeReport, runProbe } from "./probe.js";
 
+function printHelp() {
+  console.log(`Aerial local Copilot proxy
+
+Usage:
+  aerial --version
+  aerial login
+  aerial setup codex [--model <id>] [--effort <low|medium|high|xhigh|max>]
+  aerial setup claude [--model <id>] [--effort <low|medium|high|xhigh|max>]
+  aerial service install
+  aerial status [--json]
+  aerial proxy status|enable|disable [--json]
+
+Diagnostics and rollback:
+  aerial setup status [--json]
+  aerial setup restore <codex|claude|all> --latest
+  aerial service status [--json]
+  aerial teardown
+  aerial doctor
+  aerial probe [--live] [--json]
+
+Debug:
+  aerial start [--host 127.0.0.1] [--port 18181]`);
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const [command, subcommand, ...rest] = args;
@@ -51,8 +74,8 @@ async function main() {
     }
   }
 
-  if (command === "disable") {
-    runDisableCli();
+  if (command === "teardown") {
+    runTeardownCli();
     return;
   }
 
@@ -86,7 +109,16 @@ async function main() {
   process.exitCode = 1;
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
+main()
+  .then(() => {
+    // One-shot commands may leave keep-alive sockets (undici pools), a SOCKS5
+    // bridge, or stdin open, which keeps the event loop alive and hangs the CLI
+    // after the work is done. `start` is the only long-running command, so for
+    // everything else exit explicitly once main() resolves.
+    const command = process.argv[2];
+    if (command !== "start") process.exit(process.exitCode ?? 0);
+  })
+  .catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });

package/src/cli/output.js

@@ -18,6 +18,7 @@ export function printSetupSummary(status) {
     const model = client.model ? ` model=${client.model}` : "";
     const effort = ` effort=${client.effort || "missing"}`;
     console.log(`  ${client.target}: ${client.state}${model}${effort}`);
+    if (client.migration) console.log(`    migration: ${client.migration}`);
   }
   console.log(`api key: ${status.auth.api_key.exists ? "present" : "missing"}`);
   const ghSource = status.auth.github_token.source;

package/src/cli/probe.js

@@ -1,6 +1,6 @@
 import { proxyChatCompletions, proxyMessages, proxyModels, proxyResponses } from "../proxy/index.js";
-import { readJsonSafely } from "../shared/http-utils.js";
-import { aerialRoutes, usageSummary } from "../proxy/model-utils.js";
+import { readJsonSafely } from "../shared/utils.js";
+import { aerialRoutes, usageSummary } from "../proxy/models.js";
 
 function modelRoutes(model) {
   return aerialRoutes(model);