@jiayunxie/aerial 0.2.1 → 0.2.2

package/src/service/lifecycle.js

@@ -0,0 +1,301 @@
+import fs from "node:fs";
+import { githubTokenPath } from "../shared/paths.js";
+import { loadConfig } from "../shared/config.js";
+import { logEvent } from "../shared/log.js";
+import { defaultHealthFetch, classifyHealth, pollForAerialUp } from "./health.js";
+import { defaultRunCommand } from "./runner.js";
+import { requireServiceAdapter } from "./platform.js";
+import { aerialLogPath, stdioLogPath } from "./wrapper-render.js";
+import { readWrapperNodePath } from "./status.js";
+
+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 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 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 };
+}
+
+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);
+}

package/src/service/platform.js

@@ -0,0 +1,227 @@
+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 {
+  SERVICE_LABEL,
+  WIN_TASK_NAME,
+  aerialLogPath,
+  buildSchtasksArgs,
+  buildSchtasksCreateArgs,
+  cliEntry,
+  darwinWrapperPath,
+  explicitConfigDir,
+  nodeBinary,
+  plistPath,
+  renderDarwinWrapper,
+  renderPlist,
+  renderWindowsWrapper,
+  stdioLogPath,
+  uidString,
+  winWrapperPath,
+  wrapperLogConfig
+} from "./wrapper-render.js";
+
+export function isUnsupportedPlatform() {
+  return process.platform !== "darwin" && process.platform !== "win32";
+}
+
+export 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.`);
+}
+
+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 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
+  });
+  atomicWriteFile(wrapper, wrapperContent, { mode: 0o755 });
+  const file = plistPath();
+  const plistContent = renderPlist({ wrapperPath: wrapper });
+  atomicWriteFile(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
+  });
+  atomicWriteFile(wrapper, wrapperContent);
+  const args = buildSchtasksCreateArgs({ wrapperPath: wrapper });
+  const create = ctx.run("schtasks.exe", args);
+  return { wrapper, create };
+}
+
+export 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 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;
+}
+
+export function serviceState(ctx) {
+  const adapter = serviceAdapter(ctx);
+  if (adapter) return adapter.state();
+  return { installed: false, loaded: false, reason: "unsupported_platform" };
+}
+
+export function requireServiceAdapter(ctx, action) {
+  const adapter = serviceAdapter(ctx);
+  if (!adapter) throw unsupportedError(action);
+  return adapter;
+}

package/src/service/runner.js

@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process";
+
+export 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
+  };
+}