@moondeck/station 0.0.1 → 1.0.1

package/scripts/install/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-OS service-installer contract (ADR-028).
+ *
+ * `host-agent/src/cli.ts` dispatches `install`/`uninstall`/`start`/`stop`/
+ * `restart`/`status` to one of `darwin.ts` / `linux.ts` / `win.ts` based on
+ * `process.platform`. Each module exports an `installer: Installer`.
+ *
+ * Bash-3.2 constraint does NOT apply here — these are TypeScript.
+ */
+
+export interface InstallContext {
+  /** Absolute command the service runs (e.g. the `uai-host` binary). */
+  execPath: string;
+  /** Arguments for that command (e.g. ["run"]). */
+  args: string[];
+  /** Absolute working directory for the service. */
+  cwd: string;
+  /** PATH captured for the service. Managed installs prepend the stable shim. */
+  envPath?: string;
+  /** Register the service without launching it (fresh, unenrolled hosts). */
+  startOnInstall?: boolean;
+  /** Public install transaction which owns this definition replacement. */
+  definitionInstallIntent?: {
+    readonly nonce: string;
+    readonly ownerPid: number;
+  };
+  /**
+   * When true, print the unit file + the load commands instead of executing.
+   * Used by CI tests (no launchd/systemd/winsw side effects).
+   */
+  dryRun: boolean;
+}
+
+export interface ServiceManagerState {
+  /** The canonical job/unit is currently loaded by the service manager. */
+  readonly loaded: boolean;
+  /** A daemon is active or the manager has an in-flight activation/restart. */
+  readonly active: boolean;
+  /** The job/unit is enabled for a future login or reboot. */
+  readonly enabled: boolean;
+}
+
+export interface ServiceDefinitionState {
+  readonly ownership: "missing" | "managed" | "legacy";
+  readonly manager: ServiceManagerState;
+}
+
+export interface Installer {
+  /** Write the unit/plist/xml and load it. */
+  install(ctx: InstallContext): Promise<void>;
+  /** Unload + remove the unit. */
+  uninstall(dryRun?: boolean): Promise<void>;
+  start(dryRun?: boolean): Promise<void>;
+  stop(dryRun?: boolean): Promise<void>;
+  /** Owner-authorized stop used before a first managed conversion. */
+  stopForInstall(
+    installIntent: string,
+    priorManager: ServiceManagerState,
+  ): Promise<void>;
+  /** Owner-authorized idempotent resume after command-graph rollback. */
+  resumeServiceForInstall(
+    installIntent: string,
+    priorManager: ServiceManagerState,
+  ): Promise<void>;
+  restart(dryRun?: boolean): Promise<void>;
+  /** Human-readable one-line status (e.g. "running (pid 1234)"). */
+  status(): Promise<string>;
+  /** Resume/rollback an interrupted transactional definition replacement. */
+  reconcileDefinitionInstall(installIntent?: string): Promise<void>;
+  /** Restore definition/static manager state without launching the prior command. */
+  prepareDefinitionInstallRollback(installIntent: string): Promise<void>;
+  /** Resume the recorded prior service after runtime commands have been restored. */
+  resumeDefinitionInstallRollback(installIntent: string): Promise<void>;
+  /** Commit a definition replacement after the enclosing install attests. */
+  completeDefinitionInstall(installIntent?: string): Promise<void>;
+  /** Classify the canonical definition and snapshot its manager lifecycle state. */
+  definitionState(managedCommand: string): Promise<ServiceDefinitionState>;
+}

package/scripts/install/util.ts

@@ -0,0 +1,254 @@
+/**
+ * Shared install helpers (ADR-028). A `step` runs a command, or in dry-run
+ * prints it (so CI can assert the install plan without launchd/systemd/winsw
+ * side effects).
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fchmodSync,
+  fstatSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, basename, join } from "node:path";
+
+import { systemUserBusProbe, withUserBusEnv } from "../../lib/user-bus-env";
+
+export interface StepResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
+
+export type StepExecutor = (
+  dryRun: boolean,
+  cmd: string,
+  args: string[],
+) => StepResult;
+
+export type DefinitionSnapshot =
+  | { readonly exists: false }
+  | { readonly exists: true; readonly bytes: Buffer; readonly mode: number };
+
+export const MAX_SERVICE_DEFINITION_BYTES = 1024 * 1024;
+export const MAX_SERVICE_INSTALL_JOURNAL_BYTES = 2 * 1024 * 1024;
+
+export type DirectorySync = (directory: string) => void;
+
+function readBounded(fd: number, maximumBytes: number, description: string): Buffer {
+  const bytes = Buffer.allocUnsafe(maximumBytes + 1);
+  let length = 0;
+  while (length < bytes.length) {
+    const read = readSync(fd, bytes, length, bytes.length - length, null);
+    if (read === 0) break;
+    length += read;
+  }
+  if (length > maximumBytes) {
+    throw new Error(`${description} exceeds ${maximumBytes} bytes`);
+  }
+  return bytes.subarray(0, length);
+}
+
+/** Read a service definition without following a surprising symlink. */
+export function snapshotDefinition(file: string): DefinitionSnapshot {
+  let fd: number;
+  try {
+    fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { exists: false };
+    throw error;
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) {
+      throw new Error(`service definition is not a regular file: ${file}`);
+    }
+    if (stat.size > MAX_SERVICE_DEFINITION_BYTES) {
+      throw new Error(`service definition exceeds ${MAX_SERVICE_DEFINITION_BYTES} bytes: ${file}`);
+    }
+    const bytes = readBounded(
+      fd,
+      MAX_SERVICE_DEFINITION_BYTES,
+      `service definition ${file}`,
+    );
+    return {
+      exists: true,
+      bytes,
+      mode: stat.mode & 0o7777,
+    };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Atomically replace a definition and sync both its bytes and directory entry. */
+export function writeDefinitionDurable(
+  file: string,
+  contents: string | Buffer,
+  mode = 0o644,
+  syncDirectoryEntry: DirectorySync = syncDirectoryDurable,
+): void {
+  const directory = dirname(file);
+  mkdirSync(directory, { recursive: true });
+  const temporary = join(
+    directory,
+    `.${basename(file)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+  let fd: number | undefined;
+  try {
+    fd = openSync(
+      temporary,
+      constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+    writeFileSync(fd, contents);
+    fchmodSync(fd, mode);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(temporary, file);
+    syncDirectoryEntry(directory);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function restoreDefinitionDurable(
+  file: string,
+  snapshot: DefinitionSnapshot,
+  syncDirectoryEntry: DirectorySync = syncDirectoryDurable,
+): void {
+  if (snapshot.exists) {
+    writeDefinitionDurable(file, snapshot.bytes, snapshot.mode, syncDirectoryEntry);
+    return;
+  }
+  rmSync(file, { force: true });
+  syncDirectoryEntry(dirname(file));
+}
+
+export function readPrivateJournal(file: string): string | null {
+  let fd: number;
+  try {
+    fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error(`service install journal is not regular: ${file}`);
+    if ((stat.mode & 0o077) !== 0) {
+      throw new Error(`service install journal permissions are too broad: ${file}`);
+    }
+    if (stat.size > MAX_SERVICE_INSTALL_JOURNAL_BYTES) {
+      throw new Error(
+        `service install journal exceeds ${MAX_SERVICE_INSTALL_JOURNAL_BYTES} bytes: ${file}`,
+      );
+    }
+    return readBounded(
+      fd,
+      MAX_SERVICE_INSTALL_JOURNAL_BYTES,
+      `service install journal ${file}`,
+    ).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function removeFileDurable(file: string): void {
+  rmSync(file, { force: true });
+  syncDirectoryDurable(dirname(file));
+}
+
+export function syncDirectoryDurable(directory: string): void {
+  const fd = openSync(directory, constants.O_RDONLY);
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Run a service-manager command without deciding whether its failure is safe.
+ * Stop/uninstall need the complete result so they can distinguish an absent
+ * unit from a manager failure or a daemon which is still live.
+ */
+export const executeStep: StepExecutor = (dryRun, cmd, args) => {
+  if (dryRun) {
+    console.log(`$ ${cmd} ${args.join(" ")}`);
+    return { status: 0, stdout: "", stderr: "" };
+  }
+  // `systemctl --user` needs the user's bus; a stripped environment loses it
+  // (lib/user-bus-env.ts). Everything else inherits this process's env as is.
+  const userManager = cmd === "systemctl" && args.includes("--user");
+  const res = spawnSync(cmd, args, {
+    encoding: "utf8",
+    ...(userManager ? { env: withUserBusEnv(process.env, systemUserBusProbe()) } : {}),
+  });
+  return {
+    status: res.status,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? "",
+    error: res.error,
+  };
+};
+
+export function stepFailure(
+  cmd: string,
+  args: string[],
+  result: StepResult,
+  context?: string,
+): Error {
+  const detail = (
+    result.stderr ||
+    result.stdout ||
+    result.error?.message ||
+    `exit status ${String(result.status)}`
+  ).trim();
+  return new Error(
+    `\`${cmd} ${args.join(" ")}\` failed: ${detail}${context ? ` (${context})` : ""}`,
+  );
+}
+
+export function step(
+  dryRun: boolean,
+  cmd: string,
+  args: string[],
+  opts: { ignoreError?: boolean } = {},
+): string {
+  const result = executeStep(dryRun, cmd, args);
+  if (result.status !== 0 && !opts.ignoreError) {
+    throw stepFailure(cmd, args, result);
+  }
+  return result.stdout;
+}
+
+/** Print a unit/plist/xml file's path + contents (dry-run). */
+export function printFile(path: string, content: string): void {
+  console.log(`# ${path}`);
+  console.log(content);
+}
+
+export function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/scripts/install/win.ts

@@ -0,0 +1,143 @@
+/**
+ * Windows service install via winsw (ADR-028).
+ *
+ * Downloads a pinned winsw binary to %LOCALAPPDATA%\Moondeck\service\moondeck-station.exe,
+ * writes moondeck-station.xml beside it (winsw reads <basename>.xml), and registers
+ * with `moondeck-station.exe install`. Logs to %LOCALAPPDATA%\Moondeck\service\logs\.
+ *
+ * Untested on non-Windows hosts (dev is macOS); the dry-run plan + the XML
+ * render are covered by tests.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { STATION } from "../../src/station-identity";
+import type { InstallContext, Installer } from "./types";
+import { escapeXml, printFile, step } from "./util";
+
+// Pinned winsw release (bump deliberately).
+const WINSW_URL =
+  "https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe";
+
+function serviceDir(): string {
+  const base = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+  return join(base, STATION.logDirName, "service");
+}
+export function exePath(): string {
+  return join(serviceDir(), `${STATION.command}.exe`);
+}
+export function xmlPath(): string {
+  return join(serviceDir(), `${STATION.command}.xml`);
+}
+function logDir(): string {
+  return join(serviceDir(), "logs");
+}
+
+export interface XmlInputs {
+  execPath: string;
+  args: string[];
+  cwd: string;
+  path: string;
+  logDir: string;
+}
+
+export function renderXml(p: XmlInputs): string {
+  return `<service>
+  <id>${STATION.command}</id>
+  <name>${STATION.displayName}</name>
+  <description>${STATION.displayName} (ADR-028)</description>
+  <executable>${escapeXml(p.execPath)}</executable>
+  <arguments>${escapeXml(p.args.join(" "))}</arguments>
+  <workingdirectory>${escapeXml(p.cwd)}</workingdirectory>
+  <env name="PATH" value="${escapeXml(p.path)}" />
+  <onfailure action="restart" delay="10 sec" />
+  <log mode="roll" />
+  <logpath>${escapeXml(p.logDir)}</logpath>
+</service>
+`;
+}
+
+function inputs(ctx: InstallContext): XmlInputs {
+  return {
+    execPath: ctx.execPath,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    path: process.env.PATH ?? "",
+    logDir: logDir(),
+  };
+}
+
+async function downloadWinsw(dest: string): Promise<void> {
+  const res = await fetch(WINSW_URL);
+  if (!res.ok) throw new Error(`winsw download failed: ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  await writeFile(dest, buf);
+}
+
+async function install(ctx: InstallContext): Promise<void> {
+  const xml = renderXml(inputs(ctx));
+  if (ctx.dryRun) {
+    printFile(xmlPath(), xml);
+    console.log(`# download winsw -> ${exePath()}`);
+    console.log(`#   ${WINSW_URL}`);
+    step(true, exePath(), ["install"]);
+    step(true, exePath(), ["start"]);
+    return;
+  }
+  mkdirSync(logDir(), { recursive: true });
+  await downloadWinsw(exePath());
+  writeFileSync(xmlPath(), xml);
+  step(false, exePath(), ["install"]);
+  step(false, exePath(), ["start"]);
+}
+
+async function uninstall(dryRun = false): Promise<void> {
+  step(dryRun, exePath(), ["stop"], { ignoreError: true });
+  step(dryRun, exePath(), ["uninstall"], { ignoreError: true });
+  if (dryRun) {
+    console.log(`$ rm -f ${exePath()} ${xmlPath()}`);
+    return;
+  }
+  rmSync(exePath(), { force: true });
+  rmSync(xmlPath(), { force: true });
+}
+
+async function start(dryRun = false): Promise<void> {
+  step(dryRun, exePath(), ["start"]);
+}
+
+async function stop(dryRun = false): Promise<void> {
+  step(dryRun, exePath(), ["stop"], { ignoreError: true });
+}
+
+async function restart(dryRun = false): Promise<void> {
+  step(dryRun, exePath(), ["restart"]);
+}
+
+async function status(): Promise<string> {
+  return step(false, exePath(), ["status"], { ignoreError: true }).trim() || "unknown";
+}
+
+export const installer: Installer = {
+  install,
+  uninstall,
+  start,
+  stop,
+  stopForInstall: async () => undefined,
+  resumeServiceForInstall: async () => undefined,
+  restart,
+  status,
+  // Standalone managed runtimes currently reject Windows before service
+  // installation, so there is no Windows definition journal to reconcile.
+  reconcileDefinitionInstall: async () => undefined,
+  prepareDefinitionInstallRollback: async () => undefined,
+  resumeDefinitionInstallRollback: async () => undefined,
+  completeDefinitionInstall: async () => undefined,
+  definitionState: async () => ({
+    ownership: "missing",
+    manager: { loaded: false, active: false, enabled: false },
+  }),
+};

package/src/activation-respawn.ts

@@ -0,0 +1,155 @@
+/**
+ * The macOS activation restart must not depend on launchd KeepAlive.
+ *
+ * A staged runtime activation (the in-app Update, `uai-host update`, the
+ * remote hostRestart) drains in-flight work and exits with
+ * MANAGED_UPDATE_RESTART_EXIT_CODE (75) so the service supervisor relaunches
+ * `runtime/current`. On Linux `Restart=on-failure` does exactly that. On
+ * macOS the LaunchAgent is `KeepAlive: true` — and twice on 2026-09-06 launchd
+ * did NOT respawn the job: `launchctl print gui/501/com.runuai.host` sat at
+ * `state = not running`, `last exit code = 75: EX_TEMPFAIL`,
+ * `pended nondemand spawn = inefficient` until the operator ran
+ * `uai-host start` (a plain `launchctl kickstart` of the job), which recovered
+ * it instantly.
+ *
+ * So the exiting process schedules that kickstart itself, from a child that
+ * survives it: a detached (`setsid`, so it leaves the job's process group and
+ * launchd's exit-time group cleanup cannot reach it), unref'd, stdio-less
+ * shell that sleeps a few seconds and then kickstarts the job. Plain
+ * `kickstart` first — a no-op when KeepAlive did respawn, so a fresh instance
+ * is never killed mid-boot — and `kickstart -k` as the fallback should launchd
+ * refuse the plain one (kill whatever is there and start again; by then
+ * nothing of ours should be running).
+ *
+ * It is scheduled only where it can matter: darwin, not under the desktop
+ * app's supervisor (which relaunches the agent on exit itself), and only when
+ * launchd is this process's parent — a `uai-host run` in a terminal, or a test
+ * spawning the CLI, has nothing to kick and must never touch a live service.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+
+import { launchdJobTarget } from "../scripts/install/darwin";
+
+/** Long enough for a KeepAlive respawn, if launchd honours it, to have
+ * happened first (so the plain kickstart is a no-op); short enough that the
+ * host is back within seconds when it does not. */
+export const ACTIVATION_RESPAWN_DELAY_SECONDS = 5;
+
+export const ACTIVATION_RESPAWN_SHELL = "/bin/sh";
+/** Absolute: the detached shell inherits the service environment, and a
+ * launchd-spawned job's PATH is whatever the plist captured at install. */
+export const ACTIVATION_RESPAWN_LAUNCHCTL = "/bin/launchctl";
+/** `$1` = delay in seconds, `$2` = the launchd job target. Positional, never
+ * interpolated, so the command line stays inert whatever the inputs. */
+export const ACTIVATION_RESPAWN_SCRIPT = `sleep "$1"; ${ACTIVATION_RESPAWN_LAUNCHCTL} kickstart "$2" || exec ${ACTIVATION_RESPAWN_LAUNCHCTL} kickstart -k "$2"`;
+
+export interface ActivationRespawnChild {
+  on(event: "error", listener: (error: Error) => void): unknown;
+  unref(): void;
+}
+
+export interface ActivationRespawnSpawnOptions {
+  readonly detached: true;
+  readonly stdio: "ignore";
+}
+
+export type ActivationRespawnSpawn = (
+  command: string,
+  args: readonly string[],
+  options: ActivationRespawnSpawnOptions,
+) => ActivationRespawnChild;
+
+export interface ActivationRespawnSeams {
+  platform?: NodeJS.Platform;
+  /** `process.ppid`; launchd is pid 1 and the parent of every job it runs. */
+  parentPid?: number;
+  /** `process.getuid()`; `undefined` models a platform without uids. */
+  uid?: number | undefined;
+  /** `process.versions.electron` — the desktop app runs the agent as a
+   * supervised child and restarts it on exit itself. */
+  underElectron?: boolean;
+  delaySeconds?: number;
+  spawn?: ActivationRespawnSpawn;
+}
+
+export type ActivationRespawnPlan =
+  | {
+      readonly scheduled: true;
+      readonly target: string;
+      readonly command: string;
+      readonly args: readonly string[];
+      readonly delaySeconds: number;
+    }
+  | { readonly scheduled: false; readonly reason: string };
+
+/**
+ * Call immediately before `process.exit(MANAGED_UPDATE_RESTART_EXIT_CODE)`:
+ * the drain is complete, so the delay counts from the moment the old process
+ * is gone. `spawn` forks synchronously, so the child exists when this returns
+ * and the caller may exit at once.
+ */
+export function scheduleActivationRespawn(
+  seams: ActivationRespawnSeams = {},
+): ActivationRespawnPlan {
+  const platform = seams.platform ?? process.platform;
+  if (platform !== "darwin") {
+    return {
+      scheduled: false,
+      reason: `${platform} relies on its service supervisor's restart policy`,
+    };
+  }
+  if (seams.underElectron ?? Boolean(process.versions.electron)) {
+    return {
+      scheduled: false,
+      reason: "the desktop app's supervisor relaunches the agent",
+    };
+  }
+  const parentPid = seams.parentPid ?? process.ppid;
+  if (parentPid !== 1) {
+    return {
+      scheduled: false,
+      reason: `not launchd-spawned (parent pid ${parentPid}); nothing to kick`,
+    };
+  }
+  const uid = "uid" in seams ? seams.uid : process.getuid?.();
+  if (uid === undefined) {
+    return { scheduled: false, reason: "no uid to address the launchd domain" };
+  }
+  const delaySeconds = seams.delaySeconds ?? ACTIVATION_RESPAWN_DELAY_SECONDS;
+  const target = launchdJobTarget(uid);
+  const args = [
+    "-c",
+    ACTIVATION_RESPAWN_SCRIPT,
+    "moondeck-station-activation-respawn",
+    String(delaySeconds),
+    target,
+  ];
+  const spawn = seams.spawn ?? (nodeSpawn as unknown as ActivationRespawnSpawn);
+  let child: ActivationRespawnChild;
+  try {
+    child = spawn(ACTIVATION_RESPAWN_SHELL, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+  } catch (error) {
+    return {
+      scheduled: false,
+      reason: `could not spawn the respawn shell: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+  // A spawn that fails after the fork leaves KeepAlive as the only respawn —
+  // the pre-0.9.99 behaviour — and must not become an uncaught 'error' in a
+  // process that is about to exit anyway.
+  child.on("error", () => {});
+  child.unref();
+  return {
+    scheduled: true,
+    target,
+    command: ACTIVATION_RESPAWN_SHELL,
+    args,
+    delaySeconds,
+  };
+}