@jiayunxie/aerial 0.2.1 → 0.2.2

package/src/service.js

@@ -1,1182 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { configDir, apiKeyPath, githubTokenPath } from "./paths.js";
-import { loadConfig } from "./config.js";
-import { logEvent } from "./log.js";
-
-const SERVICE_LABEL = "com.jiayunxie.aerial";
-const WIN_TASK_NAME = "AerialLocalProxy";
-const PLIST_HEADER = "<!-- Generated by aerial; do not edit. Run `aerial service install` to regenerate. -->";
-const POSIX_HEADER = "# Generated by aerial; do not edit. Run `aerial service install` to regenerate.";
-const DEFAULT_WRAPPER_LOG_MAX_BYTES = 5 * 1024 * 1024;
-const DEFAULT_WRAPPER_LOG_BACKUPS = 3;
-const HEALTH_TIMEOUT_MS = 1500;
-const HEALTH_START_TIMEOUT_MS = 5000;
-const HEALTH_POLL_INTERVAL_MS = 250;
-const MIN_SERVICE_NODE_MAJOR = 24;
-const DARWIN_CODEX_NODE = "/Applications/Codex.app/Contents/Resources/node";
-
-function wrapperLogConfig() {
-  const out = { maxBytes: DEFAULT_WRAPPER_LOG_MAX_BYTES, backups: DEFAULT_WRAPPER_LOG_BACKUPS };
-  const rawMax = process.env.AERIAL_LOG_MAX_BYTES;
-  if (rawMax && /^\d+$/.test(String(rawMax).trim())) {
-    const n = Number(String(rawMax).trim());
-    if (n > 0) out.maxBytes = n;
-  }
-  const rawBackups = process.env.AERIAL_LOG_BACKUPS;
-  if (rawBackups && /^\d+$/.test(String(rawBackups).trim())) {
-    const n = Number(String(rawBackups).trim());
-    if (n >= 1) out.backups = n;
-  }
-  return out;
-}
-
-function defaultRunCommand(file, args, opts = {}) {
-  if (process.env.AERIAL_SERVICE_DRYRUN === "1") {
-    const installed = process.env.AERIAL_SERVICE_DRYRUN_INSTALLED === "1";
-    const fail = process.env.AERIAL_SERVICE_DRYRUN_FAIL || "";
-    if (file === "schtasks.exe" && Array.isArray(args)) {
-      if (args.includes("/Query")) {
-        if (installed) {
-          return { status: 0, signal: undefined, stdout: "TaskName: \\AerialLocalProxy\r\nStatus: Running", stderr: "", error: undefined, dryRun: true };
-        }
-        return { status: 1, signal: undefined, stdout: "", stderr: "(dryrun) task not registered", error: undefined, dryRun: true };
-      }
-      if (args.includes("/Delete") && fail === "delete") {
-        return { status: 9, signal: undefined, stdout: "", stderr: "ERROR: Access is denied.", error: undefined, dryRun: true };
-      }
-    }
-    if (file === "launchctl" && Array.isArray(args)) {
-      if (args[0] === "list") {
-        if (installed) {
-          return { status: 0, signal: undefined, stdout: '{\n\t"PID" = 1234;\n\t"LastExitStatus" = 0;\n};', stderr: "", error: undefined, dryRun: true };
-        }
-        return { status: 1, signal: undefined, stdout: "", stderr: "(dryrun) service not loaded", error: undefined, dryRun: true };
-      }
-      if (args[0] === "bootout" && fail === "bootout") {
-        return { status: 9216, signal: undefined, stdout: "", stderr: "Boot-out failed: 5: Input/output error", error: undefined, dryRun: true };
-      }
-    }
-    return { status: 0, signal: undefined, stdout: "", stderr: "", error: undefined, dryRun: true };
-  }
-  const res = spawnSync(file, args, {
-    stdio: opts.stdio || "pipe",
-    encoding: "utf8",
-    timeout: opts.timeout || 15000,
-    env: opts.env || process.env,
-    windowsHide: true
-  });
-  return {
-    status: res.status,
-    signal: res.signal,
-    stdout: res.stdout || "",
-    stderr: res.stderr || "",
-    error: res.error
-  };
-}
-
-function parseNodeMajor(versionText) {
-  const match = /^v?(\d+)\./.exec(String(versionText || "").trim());
-  return match ? Number(match[1]) : undefined;
-}
-
-function nodeMajorOfBinary(file) {
-  if (!file || !fs.existsSync(file)) return undefined;
-  const result = spawnSync(file, ["--version"], {
-    stdio: "pipe",
-    encoding: "utf8",
-    timeout: 3000,
-    windowsHide: true
-  });
-  if (result.status !== 0) return undefined;
-  return parseNodeMajor(result.stdout || result.stderr);
-}
-
-function selectServiceNodeBinary({ requested, current, candidates = [], versionOf = nodeMajorOfBinary } = {}) {
-  if (requested) return requested;
-  if (versionOf(current) >= MIN_SERVICE_NODE_MAJOR) return current;
-  for (const candidate of candidates) {
-    if (versionOf(candidate) >= MIN_SERVICE_NODE_MAJOR) return candidate;
-  }
-  return current;
-}
-
-function serviceNodeCandidates() {
-  if (process.platform === "darwin") return [DARWIN_CODEX_NODE];
-  return [];
-}
-
-function nodeBinary() {
-  return selectServiceNodeBinary({
-    requested: process.env.AERIAL_SERVICE_NODE,
-    current: process.execPath,
-    candidates: serviceNodeCandidates()
-  });
-}
-
-function cliEntry() {
-  if (process.env.AERIAL_SERVICE_CLI) return process.env.AERIAL_SERVICE_CLI;
-  return path.join(path.dirname(fileURLToPath(import.meta.url)), "cli.js");
-}
-
-function logsDir() {
-  return process.env.AERIAL_LOG_DIR || path.join(configDir(), "logs");
-}
-
-function aerialLogPath() {
-  return path.join(logsDir(), "aerial.log");
-}
-
-function stdioLogPath() {
-  return path.join(logsDir(), "aerial-stdio.log");
-}
-
-function plistPath() {
-  return path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
-}
-
-function darwinWrapperPath() {
-  return path.join(configDir(), "bin", "aerial-service.sh");
-}
-
-function winWrapperPath() {
-  return path.join(configDir(), "bin", "aerial-service.ps1");
-}
-
-function ensureDir(file) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-}
-
-function atomicWriteText(file, content, { mode } = {}) {
-  ensureDir(file);
-  const tmp = `${file}.aerial-svc-tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-  const opts = mode !== undefined ? { mode } : undefined;
-  fs.writeFileSync(tmp, content, opts);
-  try {
-    if (process.platform === "win32" && fs.existsSync(file)) fs.unlinkSync(file);
-    fs.renameSync(tmp, file);
-  } catch (err) {
-    try { fs.unlinkSync(tmp); } catch {}
-    throw err;
-  }
-  if (process.platform !== "win32" && mode !== undefined) {
-    try { fs.chmodSync(file, mode); } catch {}
-  }
-}
-
-function xmlEscape(value) {
-  return String(value)
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-function shEscape(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
-function psEscape(value) {
-  return `'${String(value).replace(/'/g, "''")}'`;
-}
-
-function uidString() {
-  if (process.platform !== "darwin") return "";
-  const uid = process.getuid?.();
-  return uid === undefined || uid === null ? "" : String(uid);
-}
-
-function explicitConfigDir() {
-  const v = process.env.AERIAL_CONFIG_DIR;
-  return v && v.trim() ? v : undefined;
-}
-
-export function renderPlist({ label = SERVICE_LABEL, wrapperPath: wrapper }) {
-  return [
-    '<?xml version="1.0" encoding="UTF-8"?>',
-    PLIST_HEADER,
-    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
-    '<plist version="1.0">',
-    "<dict>",
-    "  <key>Label</key>",
-    `  <string>${xmlEscape(label)}</string>`,
-    "  <key>ProgramArguments</key>",
-    "  <array>",
-    "    <string>/bin/sh</string>",
-    `    <string>${xmlEscape(wrapper)}</string>`,
-    "  </array>",
-    "  <key>RunAtLoad</key>",
-    "  <true/>",
-    "  <key>KeepAlive</key>",
-    "  <dict>",
-    "    <key>SuccessfulExit</key>",
-    "    <false/>",
-    "    <key>Crashed</key>",
-    "    <true/>",
-    "  </dict>",
-    "  <key>ThrottleInterval</key>",
-    "  <integer>10</integer>",
-    "</dict>",
-    "</plist>",
-    ""
-  ].join("\n");
-}
-
-export function renderDarwinWrapper({ nodePath, cliPath, host, port, stdioLog, aerialLog, configDir: cfg, maxBytes, backups }) {
-  const max = Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : DEFAULT_WRAPPER_LOG_MAX_BYTES;
-  const keep = Number.isInteger(backups) && backups >= 1 ? backups : DEFAULT_WRAPPER_LOG_BACKUPS;
-  const lines = [
-    "#!/bin/sh",
-    POSIX_HEADER,
-    "set -e",
-    `STDIO_LOG=${shEscape(stdioLog)}`,
-    `AERIAL_LOG_FILE=${shEscape(aerialLog)}`,
-    `MAX_BYTES=${max}`,
-    `BACKUPS=${keep}`,
-    `NODE_BIN=${shEscape(nodePath)}`,
-    `CLI_ENTRY=${shEscape(cliPath)}`,
-    `HOST=${shEscape(host)}`,
-    `PORT=${Number(port)}`,
-    "STDIO_DIR=$(dirname \"$STDIO_LOG\")",
-    "AERIAL_DIR=$(dirname \"$AERIAL_LOG_FILE\")",
-    "mkdir -p \"$STDIO_DIR\" \"$AERIAL_DIR\"",
-    "if [ -f \"$STDIO_LOG\" ]; then",
-    "  SIZE=$(wc -c < \"$STDIO_LOG\" | tr -d ' ')",
-    "  if [ \"$SIZE\" -gt \"$MAX_BYTES\" ]; then",
-    "    i=$((BACKUPS - 1))",
-    "    while [ \"$i\" -ge 1 ]; do",
-    "      SRC=\"$STDIO_LOG.$i\"",
-    "      DST=\"$STDIO_LOG.$((i + 1))\"",
-    "      if [ -f \"$SRC\" ]; then mv \"$SRC\" \"$DST\"; fi",
-    "      i=$((i - 1))",
-    "    done",
-    "    mv \"$STDIO_LOG\" \"$STDIO_LOG.1\"",
-    "  fi",
-    "fi",
-    "export AERIAL_LOG_FILE",
-    `export AERIAL_LOG_MAX_BYTES=${max}`,
-    `export AERIAL_LOG_BACKUPS=${keep}`
-  ];
-  if (cfg) lines.push(`export AERIAL_CONFIG_DIR=${shEscape(cfg)}`);
-  lines.push("exec \"$NODE_BIN\" \"$CLI_ENTRY\" start --host \"$HOST\" --port \"$PORT\" >> \"$STDIO_LOG\" 2>&1");
-  lines.push("");
-  return lines.join("\n");
-}
-
-export function renderWindowsWrapper({ nodePath, cliPath, host, port, stdioLog, aerialLog, configDir: cfg, maxBytes, backups }) {
-  const max = Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : DEFAULT_WRAPPER_LOG_MAX_BYTES;
-  const keep = Number.isInteger(backups) && backups >= 1 ? backups : DEFAULT_WRAPPER_LOG_BACKUPS;
-  const lines = [
-    POSIX_HEADER,
-    "$ErrorActionPreference = 'Stop'",
-    `$node = ${psEscape(nodePath)}`,
-    `$cli  = ${psEscape(cliPath)}`,
-    `$serviceHost = ${psEscape(host)}`,
-    `$servicePort = ${Number(port)}`,
-    `$stdioLog = ${psEscape(stdioLog)}`,
-    `$aerialLog = ${psEscape(aerialLog)}`,
-    `$maxBytes = ${max}`,
-    `$backups = ${keep}`,
-    "$stdioDir = Split-Path -Parent $stdioLog",
-    "$aerialDir = Split-Path -Parent $aerialLog",
-    "if (-not (Test-Path -LiteralPath $stdioDir)) { New-Item -ItemType Directory -Path $stdioDir | Out-Null }",
-    "if (-not (Test-Path -LiteralPath $aerialDir)) { New-Item -ItemType Directory -Path $aerialDir | Out-Null }",
-    "if (Test-Path -LiteralPath $stdioLog) {",
-    "  $size = (Get-Item -LiteralPath $stdioLog).Length",
-    "  if ($size -gt $maxBytes) {",
-    "    for ($i = $backups - 1; $i -ge 1; $i--) {",
-    "      $src = \"$stdioLog.$i\"",
-    "      $dst = \"$stdioLog.$($i + 1)\"",
-    "      if (Test-Path -LiteralPath $src) {",
-    "        if (Test-Path -LiteralPath $dst) { Remove-Item -LiteralPath $dst -Force }",
-    "        Move-Item -LiteralPath $src -Destination $dst",
-    "      }",
-    "    }",
-    "    if (Test-Path -LiteralPath \"$stdioLog.1\") { Remove-Item -LiteralPath \"$stdioLog.1\" -Force }",
-    "    Move-Item -LiteralPath $stdioLog -Destination \"$stdioLog.1\"",
-    "  }",
-    "}",
-    "$env:AERIAL_LOG_FILE = $aerialLog",
-    "$env:AERIAL_LOG_MAX_BYTES = \"$maxBytes\"",
-    "$env:AERIAL_LOG_BACKUPS = \"$backups\""
-  ];
-  if (cfg) lines.push(`$env:AERIAL_CONFIG_DIR = ${psEscape(cfg)}`);
-  lines.push("& $node $cli start --host $serviceHost --port $servicePort *>> $stdioLog");
-  lines.push("");
-  return lines.join("\r\n");
-}
-
-function quoteSchtasksTR(command) {
-  const wrapped = command.replace(/"/g, '\\"');
-  return `\\"${wrapped}\\"`;
-}
-
-export function buildSchtasksCreateArgs({ taskName = WIN_TASK_NAME, wrapperPath: wrapper }) {
-  const cmd = `powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${wrapper}"`;
-  return [
-    "/Create",
-    "/TN", taskName,
-    "/SC", "ONLOGON",
-    "/RL", "LIMITED",
-    "/F",
-    "/TR", quoteSchtasksTR(cmd)
-  ];
-}
-
-function buildSchtasksArgs(action, taskName = WIN_TASK_NAME) {
-  if (action === "delete") return ["/Delete", "/TN", taskName, "/F"];
-  if (action === "run") return ["/Run", "/TN", taskName];
-  if (action === "end") return ["/End", "/TN", taskName];
-  if (action === "query") return ["/Query", "/TN", taskName, "/FO", "LIST"];
-  throw new Error(`Unsupported schtasks action: ${action}`);
-}
-
-function isUnsupportedPlatform() {
-  return process.platform !== "darwin" && process.platform !== "win32";
-}
-
-function unsupportedError(action) {
-  const platform = process.platform;
-  return new Error(`aerial service ${action}: unsupported platform (${platform}). Service management is implemented for macOS (launchd) and Windows (Task Scheduler). On ${platform}, run \`aerial start\` directly or wrap it in your own init system.`);
-}
-
-async function defaultHealthFetch(host, port) {
-  if (process.env.AERIAL_SERVICE_DRYRUN === "1") {
-    return { ok: false, error: "dryrun" };
-  }
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
-  try {
-    const res = await fetch(`http://${host}:${port}/health`, { signal: controller.signal });
-    let body;
-    let parseFailed = false;
-    try {
-      body = await res.json();
-    } catch {
-      parseFailed = true;
-    }
-    return { ok: res.ok, status: res.status, body, parseFailed };
-  } catch (err) {
-    return { ok: false, error: err.message };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function classifyHealth(probe) {
-  if (!probe || probe.error) return { mode: "absent" };
-  if (probe.status !== 200) return { mode: "absent", httpStatus: probe.status };
-  if (probe.parseFailed) return { mode: "port_conflict", reason: "health body is not JSON" };
-  if (!probe.body || probe.body.service !== "aerial") {
-    return { mode: "port_conflict", reason: "200 response but not Aerial" };
-  }
-  return { mode: "aerial_running", body: probe.body };
-}
-
-async function pollForAerialUp(host, port, healthFetch, deadlineMs = HEALTH_START_TIMEOUT_MS) {
-  const fetcher = healthFetch || defaultHealthFetch;
-  const start = Date.now();
-  let lastProbe;
-  let lastCls;
-  let attempts = 0;
-  while (Date.now() - start < deadlineMs) {
-    attempts += 1;
-    lastProbe = await fetcher(host, port);
-    lastCls = classifyHealth(lastProbe);
-    if (lastCls.mode === "aerial_running" || lastCls.mode === "port_conflict") {
-      return { cls: lastCls, probe: lastProbe, attempts, elapsedMs: Date.now() - start };
-    }
-    await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL_MS));
-  }
-  return { cls: lastCls || { mode: "absent" }, probe: lastProbe, attempts, elapsedMs: Date.now() - start };
-}
-
-function unescapeShSingleQuoted(line, prefix) {
-  if (!line.startsWith(prefix)) return undefined;
-  const rest = line.slice(prefix.length);
-  if (!rest.startsWith("'")) return undefined;
-  let i = 1;
-  let out = "";
-  while (i < rest.length) {
-    const ch = rest[i];
-    if (ch === "'") {
-      if (rest.slice(i, i + 4) === "'\\''") {
-        out += "'";
-        i += 4;
-        continue;
-      }
-      return out;
-    }
-    out += ch;
-    i += 1;
-  }
-  return undefined;
-}
-
-function unescapePsSingleQuoted(line, prefix) {
-  if (!line.startsWith(prefix)) return undefined;
-  const rest = line.slice(prefix.length);
-  if (!rest.startsWith("'")) return undefined;
-  let i = 1;
-  let out = "";
-  while (i < rest.length) {
-    const ch = rest[i];
-    if (ch === "'") {
-      if (rest[i + 1] === "'") {
-        out += "'";
-        i += 2;
-        continue;
-      }
-      return out;
-    }
-    out += ch;
-    i += 1;
-  }
-  return undefined;
-}
-
-function parseWrapperPaths(wrapperFile) {
-  if (!wrapperFile) return { node: undefined, cli: undefined };
-  try {
-    if (!fs.existsSync(wrapperFile)) return { node: undefined, cli: undefined };
-    const data = fs.readFileSync(wrapperFile, "utf8");
-    const lines = data.split(/\r?\n/);
-    if (wrapperFile.endsWith(".sh")) {
-      let node;
-      let cli;
-      for (const line of lines) {
-        if (node === undefined) {
-          const candidate = unescapeShSingleQuoted(line, "NODE_BIN=");
-          if (candidate !== undefined) node = candidate;
-        }
-        if (cli === undefined) {
-          const candidate = unescapeShSingleQuoted(line, "CLI_ENTRY=");
-          if (candidate !== undefined) cli = candidate;
-        }
-        if (node !== undefined && cli !== undefined) break;
-      }
-      return { node, cli };
-    }
-    if (wrapperFile.endsWith(".ps1")) {
-      let node;
-      let cli;
-      for (const line of lines) {
-        if (node === undefined) {
-          const m = line.match(/^\$node\s*=\s*(.*)$/);
-          if (m) {
-            const candidate = unescapePsSingleQuoted(m[1].trim(), "");
-            if (candidate !== undefined) node = candidate;
-          }
-        }
-        if (cli === undefined) {
-          const m = line.match(/^\$cli\s*=\s*(.*)$/);
-          if (m) {
-            const candidate = unescapePsSingleQuoted(m[1].trim(), "");
-            if (candidate !== undefined) cli = candidate;
-          }
-        }
-        if (node !== undefined && cli !== undefined) break;
-      }
-      return { node, cli };
-    }
-  } catch {}
-  return { node: undefined, cli: undefined };
-}
-
-function readWrapperNodePath(wrapperFile) {
-  return parseWrapperPaths(wrapperFile).node;
-}
-
-export const STALE_REASONS = Object.freeze({
-  WRAPPER_MISSING: "wrapper_missing",
-  WRAPPER_NODE_MISSING: "wrapper_node_missing",
-  WRAPPER_CLI_MISSING: "wrapper_cli_missing",
-  WRAPPER_LOG_CONFIG_UNPARSEABLE: "wrapper_log_config_unparseable"
-});
-
-function wrapperBlock(state) {
-  if (!state || state.installed !== true) {
-    return { stale: false, staleReasons: [] };
-  }
-  let wrapperPath;
-  if (process.platform === "darwin") wrapperPath = darwinWrapperPath();
-  else if (process.platform === "win32") wrapperPath = winWrapperPath();
-  const wrapperFileExists = wrapperPath ? fs.existsSync(wrapperPath) : false;
-  const staleReasons = [];
-  if (!wrapperFileExists) {
-    return {
-      path: wrapperPath,
-      nodePath: undefined,
-      nodeExists: undefined,
-      cliPath: undefined,
-      cliExists: undefined,
-      logConfigParseable: undefined,
-      stale: true,
-      staleReasons: [STALE_REASONS.WRAPPER_MISSING]
-    };
-  }
-  const { node: nodePath, cli: cliPath } = parseWrapperPaths(wrapperPath);
-  const nodeExists = nodePath ? fs.existsSync(nodePath) : false;
-  const cliExists = cliPath ? fs.existsSync(cliPath) : false;
-  const logConfigParseable = parseWrapperLogValues(wrapperPath) !== null;
-  if (!nodeExists) staleReasons.push(STALE_REASONS.WRAPPER_NODE_MISSING);
-  if (!cliExists) staleReasons.push(STALE_REASONS.WRAPPER_CLI_MISSING);
-  if (!logConfigParseable) staleReasons.push(STALE_REASONS.WRAPPER_LOG_CONFIG_UNPARSEABLE);
-  return {
-    path: wrapperPath,
-    nodePath,
-    nodeExists,
-    cliPath,
-    cliExists,
-    logConfigParseable,
-    stale: staleReasons.length > 0,
-    staleReasons
-  };
-}
-
-function healthFailedDiagnostics({ wrapper, probe, attempts, elapsedMs }) {
-  const out = {
-    stdioLog: stdioLogPath(),
-    aerialLog: aerialLogPath(),
-    wrapperNode: readWrapperNodePath(wrapper),
-    health: { attempts, elapsedMs }
-  };
-  if (probe && probe.error) out.health.lastError = probe.error;
-  if (probe && probe.status !== undefined) out.health.lastStatus = probe.status;
-  return out;
-}
-
-function authFileStatus(file) {
-  if (!fs.existsSync(file)) return { file, state: "missing" };
-  try {
-    const data = fs.readFileSync(file, "utf8");
-    if (!data || !data.trim()) return { file, state: "invalid", reason: "empty" };
-    return { file, state: "present" };
-  } catch (err) {
-    return { file, state: "invalid", reason: err.message };
-  }
-}
-
-function authBlock() {
-  return {
-    api_key: authFileStatus(apiKeyPath()),
-    github_token: authFileStatus(githubTokenPath())
-  };
-}
-
-function statFile(file) {
-  if (!file) return { exists: false };
-  try {
-    if (!fs.existsSync(file)) return { exists: false };
-    return { exists: true, size: fs.statSync(file).size };
-  } catch {
-    return { exists: false };
-  }
-}
-
-function logsBlock() {
-  const dir = logsDir();
-  const primary = aerialLogPath();
-  const stdio = stdioLogPath();
-  let wrapperFile;
-  if (process.platform === "darwin") wrapperFile = darwinWrapperPath();
-  else if (process.platform === "win32") wrapperFile = winWrapperPath();
-  const parsed = wrapperFile ? parseWrapperLogValues(wrapperFile) : null;
-  let maxBytes;
-  let rotateKeep;
-  let source;
-  if (parsed) {
-    maxBytes = parsed.maxBytes;
-    rotateKeep = parsed.backups;
-    source = "installed-wrapper";
-  } else {
-    const cfg = wrapperLogConfig();
-    maxBytes = cfg.maxBytes;
-    rotateKeep = cfg.backups;
-    source = "next-install-default";
-  }
-  return {
-    dir,
-    primary: { file: primary, ...statFile(primary) },
-    stdio: { file: stdio, ...statFile(stdio) },
-    maxFileBytes: maxBytes,
-    rotateKeep,
-    source
-  };
-}
-
-function parseWrapperLogValues(file) {
-  if (!file) return null;
-  try {
-    if (!fs.existsSync(file)) return null;
-    const data = fs.readFileSync(file, "utf8");
-    let maxBytes;
-    let backups;
-    if (file.endsWith(".sh")) {
-      const m = data.match(/^MAX_BYTES=(\d+)\s*$/m);
-      const b = data.match(/^BACKUPS=(\d+)\s*$/m);
-      if (m) maxBytes = Number(m[1]);
-      if (b) backups = Number(b[1]);
-    } else if (file.endsWith(".ps1")) {
-      const m = data.match(/^\$maxBytes\s*=\s*(\d+)\s*$/m);
-      const b = data.match(/^\$backups\s*=\s*(\d+)\s*$/m);
-      if (m) maxBytes = Number(m[1]);
-      if (b) backups = Number(b[1]);
-    }
-    if (!Number.isInteger(maxBytes) || maxBytes <= 0) return null;
-    if (!Number.isInteger(backups) || backups < 1) return null;
-    return { maxBytes, backups };
-  } catch {
-    return null;
-  }
-}
-
-function darwinServiceState(ctx) {
-  const r = ctx.run("launchctl", ["list", SERVICE_LABEL]);
-  const installed = fs.existsSync(plistPath());
-  if (!installed) return { installed: false, loaded: false };
-  if (r.status !== 0) return { installed: true, loaded: false };
-  const pidMatch = /"PID"\s*=\s*(\d+)/.exec(r.stdout);
-  const lastExitMatch = /"LastExitStatus"\s*=\s*(-?\d+)/.exec(r.stdout);
-  return {
-    installed: true,
-    loaded: true,
-    pid: pidMatch ? Number(pidMatch[1]) : undefined,
-    lastExitStatus: lastExitMatch ? Number(lastExitMatch[1]) : undefined
-  };
-}
-
-function windowsServiceState(ctx) {
-  const r = ctx.run("schtasks.exe", buildSchtasksArgs("query"));
-  if (r.status !== 0) return { installed: false, loaded: false };
-  const statusMatch = /Status:\s*(\S+)/i.exec(r.stdout);
-  const status = statusMatch ? statusMatch[1].trim() : undefined;
-  return { installed: true, loaded: status === "Running", status };
-}
-
-function serviceState(ctx) {
-  const adapter = serviceAdapter(ctx);
-  if (adapter) return adapter.state();
-  return { installed: false, loaded: false, reason: "unsupported_platform" };
-}
-
-function tokenWarning() {
-  const tokenFile = githubTokenPath();
-  if (fs.existsSync(tokenFile)) {
-    try {
-      const data = fs.readFileSync(tokenFile, "utf8");
-      if (data && data.trim()) return undefined;
-    } catch {}
-  }
-  const envToken = process.env.AERIAL_GITHUB_TOKEN;
-  const envOnly = envToken && envToken.trim();
-  const message = envOnly
-    ? "AERIAL_GITHUB_TOKEN is set in this shell only; the background service does not inherit it. Run `aerial login` to persist a service-readable GitHub token, otherwise proxy requests return 503."
-    : "GitHub token is not configured. Service will start, but proxy requests return 503 until you run `aerial login`.";
-  return { level: "warning", code: "github_token_missing", message };
-}
-
-function darwinWriteDefinition() {
-  const wrapper = darwinWrapperPath();
-  const config = loadConfig();
-  const logCfg = wrapperLogConfig();
-  const wrapperContent = renderDarwinWrapper({
-    nodePath: nodeBinary(),
-    cliPath: cliEntry(),
-    host: config.host,
-    port: config.port,
-    stdioLog: stdioLogPath(),
-    aerialLog: aerialLogPath(),
-    configDir: explicitConfigDir(),
-    maxBytes: logCfg.maxBytes,
-    backups: logCfg.backups
-  });
-  atomicWriteText(wrapper, wrapperContent, { mode: 0o755 });
-  const file = plistPath();
-  const plistContent = renderPlist({ wrapperPath: wrapper });
-  atomicWriteText(file, plistContent, { mode: 0o644 });
-  return { file, wrapper };
-}
-
-function darwinBootstrap(ctx) {
-  const file = plistPath();
-  const existing = ctx.run("launchctl", ["list", SERVICE_LABEL]);
-  if (existing.status === 0) {
-    ctx.run("launchctl", ["bootout", `gui/${uidString()}`, file], { stdio: "ignore" });
-  }
-  return ctx.run("launchctl", ["bootstrap", `gui/${uidString()}`, file]);
-}
-
-function darwinBootout(ctx) {
-  const file = plistPath();
-  return ctx.run("launchctl", ["bootout", `gui/${uidString()}`, file]);
-}
-
-function windowsWriteDefinition(ctx) {
-  const wrapper = winWrapperPath();
-  const config = loadConfig();
-  const logCfg = wrapperLogConfig();
-  const wrapperContent = renderWindowsWrapper({
-    nodePath: nodeBinary(),
-    cliPath: cliEntry(),
-    host: config.host,
-    port: config.port,
-    stdioLog: stdioLogPath(),
-    aerialLog: aerialLogPath(),
-    configDir: explicitConfigDir(),
-    maxBytes: logCfg.maxBytes,
-    backups: logCfg.backups
-  });
-  atomicWriteText(wrapper, wrapperContent);
-  const args = buildSchtasksCreateArgs({ wrapperPath: wrapper });
-  const create = ctx.run("schtasks.exe", args);
-  return { wrapper, create };
-}
-
-function serviceAdapter(ctx) {
-  if (process.platform === "darwin") {
-    return {
-      platform: "darwin",
-      wrapperPath: darwinWrapperPath,
-      state: () => darwinServiceState(ctx),
-      writeDefinition: () => {
-        const written = darwinWriteDefinition();
-        return {
-          ok: true,
-          info: { file: written.file, wrapper: written.wrapper, label: SERVICE_LABEL }
-        };
-      },
-      triggerStart: () => darwinBootstrap(ctx),
-      triggerStop: () => darwinBootout(ctx),
-      startFailureReason: "bootstrap_failed",
-      startResultKey: "bootstrap",
-      uninstall: (state) => darwinUninstall(ctx, state)
-    };
-  }
-  if (process.platform === "win32") {
-    return {
-      platform: "win32",
-      wrapperPath: winWrapperPath,
-      state: () => windowsServiceState(ctx),
-      writeDefinition: () => {
-        const written = windowsWriteDefinition(ctx);
-        const info = {
-          taskName: WIN_TASK_NAME,
-          wrapper: written.wrapper,
-          create: { status: written.create.status, stderr: written.create.stderr }
-        };
-        return { ok: written.create.status === 0, info };
-      },
-      triggerStart: () => ctx.run("schtasks.exe", buildSchtasksArgs("run")),
-      triggerStop: () => ctx.run("schtasks.exe", buildSchtasksArgs("end")),
-      startFailureReason: "run_failed",
-      startResultKey: "run",
-      uninstall: (state) => windowsUninstall(ctx, state)
-    };
-  }
-  return undefined;
-}
-
-function requireServiceAdapter(ctx, action) {
-  const adapter = serviceAdapter(ctx);
-  if (!adapter) throw unsupportedError(action);
-  return adapter;
-}
-
-function commandResultBlock(key, result) {
-  return { [key]: { status: result.status, stderr: result.stderr } };
-}
-
-function buildDefinitionRefreshFailure({ adapter, supervisor, config, definition }) {
-  const isManaged = supervisor === "service-managed";
-  const status = definition.info.create?.status;
-  const reason = isManaged ? "managed_definition_refresh_failed" : "foreground_definition_refresh_failed";
-  const message = isManaged
-    ? `schtasks /Create failed (status ${status}) while refreshing the managed-service definition. The running service was not disturbed, but wrapper/env changes were NOT applied. Resolve the underlying schtasks error and rerun \`aerial service install\`.`
-    : `Aerial is already running in the foreground on port ${config.port}. The wrapper was rewritten but schtasks /Create failed (status ${status}), so the Task Scheduler definition was NOT refreshed. Resolve the underlying schtasks error and rerun \`aerial service install\`.`;
-  return {
-    ok: false,
-    action: "install",
-    platform: adapter.platform,
-    reason,
-    ...(isManaged ? {} : { definitionUpdated: false }),
-    message,
-    warning: tokenWarning(),
-    ...definition.info
-  };
-}
-
-function buildRunningDefinitionResult({ adapter, supervisor, config, definition }) {
-  const managed = supervisor === "service-managed";
-  return {
-    ok: managed,
-    action: "install",
-    platform: adapter.platform,
-    ...(managed
-      ? {
-          note: "already running (service-managed); definition refreshed; run `aerial service restart` to apply wrapper/env changes"
-        }
-      : {
-          reason: "foreground_running",
-          message: `Aerial is already running in the foreground on port ${config.port}. The service definition has been updated, but the service was NOT started to avoid running two instances. Next step: stop the foreground process, then run \`aerial service start\`.`
-        }),
-    definitionUpdated: true,
-    warning: tokenWarning(),
-    ...definition.info
-  };
-}
-
-async function confirmStarted({ action, result, config, wrapper, healthFetch, healthDeadlineMs }) {
-  if (!result.ok) return result;
-  if (process.env.AERIAL_SERVICE_DRYRUN === "1") {
-    return { ...result, health: { ok: true, attempts: 0, elapsedMs: 0, dryRun: true } };
-  }
-  const poll = await pollForAerialUp(config.host, config.port, healthFetch, healthDeadlineMs);
-  if (poll.cls.mode === "aerial_running") {
-    return { ...result, health: { ok: true, attempts: poll.attempts, elapsedMs: poll.elapsedMs } };
-  }
-  const diagnostics = healthFailedDiagnostics({
-    wrapper,
-    probe: poll.probe,
-    attempts: poll.attempts,
-    elapsedMs: poll.elapsedMs
-  });
-  if (poll.cls.mode === "port_conflict") {
-    const prefix = action === "install" ? "After install" : "After start";
-    return {
-      ...result,
-      ok: false,
-      reason: "port_conflict",
-      message: `${prefix}, port ${config.port} is responding as a non-Aerial process: ${poll.cls.reason}. Free the port and rerun.`,
-      diagnostics
-    };
-  }
-  const message = action === "install"
-    ? `Service definition was written and start was triggered, but /health did not become Aerial within ${poll.elapsedMs}ms (${poll.attempts} attempts). Inspect logs and rerun \`aerial service status --json\`.`
-    : `Start was triggered, but /health did not become Aerial within ${poll.elapsedMs}ms (${poll.attempts} attempts). Inspect logs and rerun \`aerial service status --json\`.`;
-  return {
-    ...result,
-    ok: false,
-    reason: "health_check_failed",
-    ...(action === "install" ? { definitionWritten: true } : {}),
-    startAttempted: true,
-    message,
-    diagnostics
-  };
-}
-
-async function describeRunning(adapter, host, port, healthFetch, knownState) {
-  const probe = await (healthFetch || defaultHealthFetch)(host, port);
-  const cls = classifyHealth(probe);
-  if (cls.mode !== "aerial_running") return { cls, probe };
-  const state = knownState || adapter.state();
-  const supervisor = state.installed && state.loaded ? "service-managed" : "foreground";
-  return { cls, probe, supervisor };
-}
-
-export async function serviceInstall({ run = defaultRunCommand, healthFetch, healthDeadlineMs } = {}) {
-  const ctx = { run };
-  const adapter = requireServiceAdapter(ctx, "install");
-  const config = loadConfig();
-  const { cls, supervisor } = await describeRunning(adapter, config.host, config.port, healthFetch);
-  if (cls.mode === "port_conflict") {
-    logEvent("service_install", { platform: adapter.platform, ok: false, reason: "port_conflict" });
-    return {
-      ok: false,
-      action: "install",
-      platform: adapter.platform,
-      reason: "port_conflict",
-      message: `Port ${config.port} is already in use by a non-Aerial process: ${cls.reason}. Free the port and rerun.`
-    };
-  }
-  if (cls.mode === "aerial_running") {
-    const definition = adapter.writeDefinition();
-    if (!definition.ok) {
-      const failure = buildDefinitionRefreshFailure({ adapter, supervisor, config, definition });
-      logEvent("service_install", {
-        platform: adapter.platform,
-        ok: false,
-        reason: failure.reason,
-        status: definition.info.create?.status
-      });
-      return failure;
-    }
-    const result = buildRunningDefinitionResult({ adapter, supervisor, config, definition });
-    logEvent("service_install", {
-      platform: adapter.platform,
-      ok: result.ok,
-      reason: result.reason,
-      note: supervisor === "service-managed" ? "managed_refreshed" : undefined,
-      definitionUpdated: true
-    });
-    return result;
-  }
-
-  const definition = adapter.writeDefinition();
-  let result = {
-    ok: definition.ok,
-    action: "install",
-    platform: adapter.platform,
-    ...definition.info
-  };
-  if (!definition.ok) {
-    result.reason = "create_failed";
-  } else {
-    const start = adapter.triggerStart();
-    const triggerOk = start.status === 0;
-    result = {
-      ...result,
-      ok: triggerOk,
-      ...commandResultBlock(adapter.startResultKey, start),
-      ...(triggerOk ? {} : { reason: adapter.startFailureReason })
-    };
-  }
-  result = await confirmStarted({
-    action: "install",
-    result,
-    config,
-    wrapper: result.wrapper,
-    healthFetch,
-    healthDeadlineMs
-  });
-  result.warning = tokenWarning();
-  logEvent("service_install", { platform: adapter.platform, ok: result.ok, reason: result.reason });
-  return result;
-}
-
-export async function serviceStart({ run = defaultRunCommand, healthFetch, healthDeadlineMs } = {}) {
-  const ctx = { run };
-  const adapter = requireServiceAdapter(ctx, "start");
-  const config = loadConfig();
-  const state = adapter.state();
-  if (!state.installed) {
-    return {
-      ok: false,
-      action: "start",
-      platform: adapter.platform,
-      reason: "not_installed",
-      message: "Service is not installed. Run `aerial service install` first."
-    };
-  }
-  const { cls, supervisor } = await describeRunning(adapter, config.host, config.port, healthFetch, state);
-  if (cls.mode === "port_conflict") {
-    return {
-      ok: false,
-      action: "start",
-      platform: adapter.platform,
-      reason: "port_conflict",
-      message: `Port ${config.port} is already in use by a non-Aerial process: ${cls.reason}. Free the port and rerun.`
-    };
-  }
-  if (cls.mode === "aerial_running" && supervisor === "foreground") {
-    return {
-      ok: false,
-      action: "start",
-      platform: adapter.platform,
-      reason: "foreground_running",
-      message: `Aerial is already running in the foreground on port ${config.port}. Stop the foreground process before starting the service.`
-    };
-  }
-  if (cls.mode === "aerial_running" && supervisor === "service-managed") {
-    return {
-      ok: true,
-      action: "start",
-      platform: adapter.platform,
-      note: "already running (service-managed)",
-      warning: tokenWarning()
-    };
-  }
-  const r = adapter.triggerStart();
-  const triggerOk = r.status === 0;
-  let result = {
-    ok: triggerOk,
-    action: "start",
-    platform: adapter.platform,
-    status: r.status,
-    stderr: r.stderr,
-    warning: tokenWarning(),
-    ...(triggerOk ? {} : { reason: adapter.startFailureReason })
-  };
-  if (!triggerOk) {
-    logEvent("service_start", { platform: adapter.platform, status: r.status, reason: result.reason });
-    return result;
-  }
-  result = await confirmStarted({
-    action: "start",
-    result,
-    config,
-    wrapper: adapter.wrapperPath(),
-    healthFetch,
-    healthDeadlineMs
-  });
-  logEvent("service_start", { platform: adapter.platform, status: r.status, ok: result.ok, reason: result.reason, dryRun: result.health?.dryRun });
-  return result;
-}
-
-export function serviceStop({ run = defaultRunCommand } = {}) {
-  const ctx = { run };
-  const adapter = requireServiceAdapter(ctx, "stop");
-  const state = adapter.state();
-  if (!state.installed) {
-    return { ok: true, action: "stop", platform: adapter.platform, note: "not installed" };
-  }
-  if (!state.loaded) {
-    return { ok: true, action: "stop", platform: adapter.platform, note: "not running" };
-  }
-  const r = adapter.triggerStop();
-  logEvent("service_stop", { platform: adapter.platform, status: r.status });
-  return { ok: r.status === 0, action: "stop", platform: adapter.platform, status: r.status, stderr: r.stderr };
-}
-
-export async function serviceRestart(opts = {}) {
-  const stop = serviceStop(opts);
-  if (!stop.ok) {
-    return { ok: false, action: "restart", platform: process.platform, stop, reason: "stop_failed" };
-  }
-  const start = await serviceStart(opts);
-  return { ok: start.ok, action: "restart", platform: process.platform, stop, start, warning: start.warning };
-}
-
-function removeFileIfExists(file) {
-  if (!fs.existsSync(file)) return false;
-  try {
-    fs.unlinkSync(file);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function darwinUninstall(ctx, state) {
-  const file = plistPath();
-  const wrapper = darwinWrapperPath();
-  if (state.loaded) {
-    const bootout = darwinBootout(ctx);
-    if (bootout.status !== 0) {
-      logEvent("service_uninstall", { platform: "darwin", ok: false, reason: "bootout_failed", status: bootout.status });
-      return {
-        ok: false,
-        action: "uninstall",
-        platform: "darwin",
-        reason: "bootout_failed",
-        file,
-        wrapper,
-        bootout: { status: bootout.status, stderr: bootout.stderr },
-        message: `launchctl bootout failed (status ${bootout.status}). Service is still loaded; plist and wrapper were preserved. Retry with \`aerial service uninstall\`.`
-      };
-    }
-    removeFileIfExists(file);
-    removeFileIfExists(wrapper);
-    logEvent("service_uninstall", { platform: "darwin", ok: true });
-    return { ok: true, action: "uninstall", platform: "darwin", file, wrapper, bootout: { status: bootout.status, stderr: bootout.stderr } };
-  }
-  removeFileIfExists(file);
-  removeFileIfExists(wrapper);
-  logEvent("service_uninstall", { platform: "darwin", ok: true });
-  return { ok: true, action: "uninstall", platform: "darwin", file, wrapper, bootout: { status: 0, skipped: "not_loaded" } };
-}
-
-function windowsUninstall(ctx, state) {
-  if (state.loaded) {
-    ctx.run("schtasks.exe", buildSchtasksArgs("end"));
-  }
-  const del = ctx.run("schtasks.exe", buildSchtasksArgs("delete"));
-  const wrapper = winWrapperPath();
-  const wrapperRemoved = del.status === 0 ? removeFileIfExists(wrapper) : false;
-  logEvent("service_uninstall", { platform: "win32", ok: del.status === 0 });
-  return {
-    ok: del.status === 0,
-    action: "uninstall",
-    platform: "win32",
-    taskName: WIN_TASK_NAME,
-    wrapper,
-    wrapperRemoved,
-    delete: { status: del.status, stderr: del.stderr },
-    ...(del.status === 0 ? {} : { reason: "delete_failed", message: `schtasks /Delete failed (status ${del.status}). Task and wrapper were preserved. Retry with \`aerial service uninstall\`.` })
-  };
-}
-
-export function serviceUninstall({ run = defaultRunCommand } = {}) {
-  const ctx = { run };
-  const adapter = requireServiceAdapter(ctx, "uninstall");
-  const state = adapter.state();
-  if (!state.installed) {
-    return { ok: true, action: "uninstall", platform: adapter.platform, note: "no service installed" };
-  }
-  return adapter.uninstall(state);
-}
-
-export async function serviceStatus({ run = defaultRunCommand, healthFetch } = {}) {
-  const config = loadConfig();
-  const ctx = { run };
-  if (isUnsupportedPlatform()) {
-    return {
-      schema: "aerial.service-status.v1",
-      platform: process.platform,
-      supported: false,
-      config: { host: config.host, port: config.port },
-      service: { installed: false, loaded: false, reason: "unsupported_platform", platform: process.platform, wrapper: wrapperBlock({ installed: false }) },
-      health: { ok: false, error: "unsupported_platform" },
-      logs: logsBlock(),
-      auth: authBlock(),
-      summary: "unsupported"
-    };
-  }
-  const state = serviceState(ctx);
-  const probe = await (healthFetch || defaultHealthFetch)(config.host, config.port);
-  const cls = classifyHealth(probe);
-  const wrapper = wrapperBlock(state);
-  let supervisor;
-  if (cls.mode === "aerial_running") {
-    supervisor = state.installed && state.loaded ? "service-managed" : "foreground";
-  }
-  const health = { ...probe };
-  if (cls.mode === "port_conflict") {
-    health.portConflict = true;
-    health.conflictReason = cls.reason;
-  }
-  if (cls.mode === "aerial_running") {
-    health.aerial = true;
-    health.supervisor = supervisor;
-  }
-  let summary;
-  if (cls.mode === "aerial_running" && supervisor === "service-managed") summary = "running (service-managed)";
-  else if (cls.mode === "aerial_running" && supervisor === "foreground") summary = "running (foreground)";
-  else if (cls.mode === "port_conflict") summary = "port conflict (non-Aerial process on port)";
-  else if (state.installed && state.loaded) summary = "manager reports up but health failed";
-  else if (state.installed) summary = "installed (not running)";
-  else summary = "not installed";
-  return {
-    schema: "aerial.service-status.v1",
-    platform: process.platform,
-    supported: true,
-    config: { host: config.host, port: config.port },
-    service: { platform: process.platform, ...state, wrapper },
-    health,
-    logs: logsBlock(),
-    auth: authBlock(),
-    summary
-  };
-}
-
-export const _internal = {
-  SERVICE_LABEL,
-  WIN_TASK_NAME,
-  plistPath,
-  darwinWrapperPath,
-  winWrapperPath,
-  aerialLogPath,
-  stdioLogPath,
-  parseWrapperLogValues,
-  parseWrapperPaths,
-  wrapperBlock,
-  buildSchtasksArgs,
-  quoteSchtasksTR,
-  classifyHealth,
-  parseNodeMajor,
-  selectServiceNodeBinary
-};