@runuai/host 0.1.0

package/scripts/install/darwin.ts

@@ -0,0 +1,167 @@
+/**
+ * macOS service install via launchd (ADR-028).
+ *
+ * Writes ~/Library/LaunchAgents/com.runuai.host.plist (KeepAlive + RunAtLoad),
+ * logs to ~/Library/Logs/Uai/, loads with `launchctl bootstrap gui/<uid>`.
+ * The service's PATH is the operator's PATH at install time (so node/pnpm/
+ * docker/git resolve); .env.local is loaded by the host process itself.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+import type { InstallContext, Installer } from "./types";
+import { escapeXml, printFile, step } from "./util";
+
+export const LABEL = "com.runuai.host";
+
+const uid = process.getuid?.() ?? 0;
+const domain = `gui/${uid}`;
+const target = `${domain}/${LABEL}`;
+const logDir = resolve(homedir(), "Library", "Logs", "Uai");
+
+export function plistPath(): string {
+  return resolve(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+export interface PlistInputs {
+  execPath: string;
+  args: string[];
+  cwd: string;
+  path: string;
+  home: string;
+  outLog: string;
+  errLog: string;
+}
+
+export function renderPlist(p: PlistInputs): string {
+  const progArgs = [p.execPath, ...p.args]
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!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>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(p.cwd)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(p.path)}</string>
+    <key>HOME</key>
+    <string>${escapeXml(p.home)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(p.outLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(p.errLog)}</string>
+</dict>
+</plist>
+`;
+}
+
+function inputs(ctx: InstallContext): PlistInputs {
+  return {
+    execPath: ctx.execPath,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    path: process.env.PATH ?? "",
+    home: homedir(),
+    outLog: resolve(logDir, "host.out.log"),
+    errLog: resolve(logDir, "host.log"),
+  };
+}
+
+async function install(ctx: InstallContext): Promise<void> {
+  const plist = renderPlist(inputs(ctx));
+  if (ctx.dryRun) {
+    printFile(plistPath(), plist);
+    step(true, "mkdir", ["-p", logDir]);
+    step(true, "launchctl", ["bootout", target]);
+    step(true, "launchctl", ["bootstrap", domain, plistPath()]);
+    step(true, "launchctl", ["enable", target]);
+    return;
+  }
+  mkdirSync(logDir, { recursive: true });
+  mkdirSync(dirname(plistPath()), { recursive: true });
+  writeFileSync(plistPath(), plist);
+  // Reload cleanly: bootout any prior instance (ignore "not loaded"), bootstrap.
+  step(false, "launchctl", ["bootout", target], { ignoreError: true });
+  await bootstrapWithRetry();
+  step(false, "launchctl", ["enable", target], { ignoreError: true });
+}
+
+/**
+ * `bootout` unloads the old job asynchronously, so an immediate `bootstrap`
+ * can race it ("Bootstrap failed: 5: Input/output error"). Retry a few times
+ * so re-running `install` is idempotent instead of leaving nothing loaded.
+ */
+async function bootstrapWithRetry(): Promise<void> {
+  let lastErr: unknown;
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      step(false, "launchctl", ["bootstrap", domain, plistPath()]);
+      return;
+    } catch (err) {
+      lastErr = err;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+
+async function uninstall(dryRun = false): Promise<void> {
+  step(dryRun, "launchctl", ["bootout", target], { ignoreError: true });
+  if (dryRun) {
+    console.log(`$ rm -f ${plistPath()}`);
+    return;
+  }
+  rmSync(plistPath(), { force: true });
+}
+
+async function start(dryRun = false): Promise<void> {
+  // bootstrap loads + RunAtLoad starts; if already loaded that errors, so also
+  // kickstart to be sure it's running.
+  step(dryRun, "launchctl", ["bootstrap", domain, plistPath()], {
+    ignoreError: true,
+  });
+  step(dryRun, "launchctl", ["kickstart", target], { ignoreError: true });
+}
+
+async function stop(dryRun = false): Promise<void> {
+  step(dryRun, "launchctl", ["bootout", target], { ignoreError: true });
+}
+
+async function restart(dryRun = false): Promise<void> {
+  step(dryRun, "launchctl", ["kickstart", "-k", target], { ignoreError: true });
+}
+
+async function status(): Promise<string> {
+  const out = step(false, "launchctl", ["print", target], { ignoreError: true });
+  if (!out) return "not installed / not loaded";
+  const state = /state = (\S+)/.exec(out)?.[1] ?? "unknown";
+  const pid = /pid = (\d+)/.exec(out)?.[1];
+  return `${state}${pid ? ` (pid ${pid})` : ""}`;
+}
+
+export const installer: Installer = {
+  install,
+  uninstall,
+  start,
+  stop,
+  restart,
+  status,
+};

package/scripts/install/linux.ts

@@ -0,0 +1,115 @@
+/**
+ * Linux service install via a systemd **user** unit (ADR-028).
+ *
+ * Writes ~/.config/systemd/user/uai-host.service, enables it with
+ * `systemctl --user enable --now`. Logs go to journald
+ * (`journalctl --user -u uai-host`).
+ *
+ * v1 limitation (ADR-028 open question): systemd-user needs a logged-in user
+ * session unless lingering is enabled (`loginctl enable-linger <user>`); for a
+ * dedicated headless server a system unit + service user would be the move.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+import type { InstallContext, Installer } from "./types";
+import { printFile, step } from "./util";
+
+export const UNIT = "uai-host.service";
+
+export function unitPath(): string {
+  return resolve(homedir(), ".config", "systemd", "user", UNIT);
+}
+
+export interface UnitInputs {
+  execPath: string;
+  args: string[];
+  cwd: string;
+  path: string;
+}
+
+export function renderUnit(p: UnitInputs): string {
+  const exec = [p.execPath, ...p.args].join(" ");
+  return `[Unit]
+Description=Uai host service (ADR-028)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${p.cwd}
+Environment=PATH=${p.path}
+ExecStart=${exec}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function inputs(ctx: InstallContext): UnitInputs {
+  return {
+    execPath: ctx.execPath,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    path: process.env.PATH ?? "",
+  };
+}
+
+async function install(ctx: InstallContext): Promise<void> {
+  const unit = renderUnit(inputs(ctx));
+  if (ctx.dryRun) {
+    printFile(unitPath(), unit);
+    step(true, "systemctl", ["--user", "daemon-reload"]);
+    step(true, "systemctl", ["--user", "enable", "--now", UNIT]);
+    return;
+  }
+  mkdirSync(dirname(unitPath()), { recursive: true });
+  writeFileSync(unitPath(), unit);
+  step(false, "systemctl", ["--user", "daemon-reload"]);
+  step(false, "systemctl", ["--user", "enable", "--now", UNIT]);
+}
+
+async function uninstall(dryRun = false): Promise<void> {
+  step(dryRun, "systemctl", ["--user", "disable", "--now", UNIT], {
+    ignoreError: true,
+  });
+  if (dryRun) {
+    console.log(`$ rm -f ${unitPath()}`);
+    step(true, "systemctl", ["--user", "daemon-reload"]);
+    return;
+  }
+  rmSync(unitPath(), { force: true });
+  step(false, "systemctl", ["--user", "daemon-reload"], { ignoreError: true });
+}
+
+async function start(dryRun = false): Promise<void> {
+  step(dryRun, "systemctl", ["--user", "start", UNIT]);
+}
+
+async function stop(dryRun = false): Promise<void> {
+  step(dryRun, "systemctl", ["--user", "stop", UNIT], { ignoreError: true });
+}
+
+async function restart(dryRun = false): Promise<void> {
+  step(dryRun, "systemctl", ["--user", "restart", UNIT]);
+}
+
+async function status(): Promise<string> {
+  const active = step(false, "systemctl", ["--user", "is-active", UNIT], {
+    ignoreError: true,
+  }).trim();
+  return active || "unknown";
+}
+
+export const installer: Installer = {
+  install,
+  uninstall,
+  start,
+  stop,
+  restart,
+  status,
+};

package/scripts/install/types.ts

@@ -0,0 +1,35 @@
+/**
+ * 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;
+  /**
+   * 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 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>;
+  restart(dryRun?: boolean): Promise<void>;
+  /** Human-readable one-line status (e.g. "running (pid 1234)"). */
+  status(): Promise<string>;
+}

package/scripts/install/util.ts

@@ -0,0 +1,39 @@
+/**
+ * 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";
+
+export function step(
+  dryRun: boolean,
+  cmd: string,
+  args: string[],
+  opts: { ignoreError?: boolean } = {},
+): string {
+  if (dryRun) {
+    console.log(`$ ${cmd} ${args.join(" ")}`);
+    return "";
+  }
+  const res = spawnSync(cmd, args, { encoding: "utf8" });
+  if (res.status !== 0 && !opts.ignoreError) {
+    const detail = (res.stderr || res.stdout || res.error?.message || "").trim();
+    throw new Error(`\`${cmd} ${args.join(" ")}\` failed: ${detail}`);
+  }
+  return res.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, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/scripts/install/win.ts

@@ -0,0 +1,130 @@
+/**
+ * Windows service install via winsw (ADR-028).
+ *
+ * Downloads a pinned winsw binary to %LOCALAPPDATA%\Uai\service\uai-host.exe,
+ * writes uai-host.xml beside it (winsw reads <basename>.xml), and registers
+ * with `uai-host.exe install`. Logs to %LOCALAPPDATA%\Uai\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 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, "Uai", "service");
+}
+export function exePath(): string {
+  return join(serviceDir(), "uai-host.exe");
+}
+export function xmlPath(): string {
+  return join(serviceDir(), "uai-host.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>uai-host</id>
+  <name>Uai host service</name>
+  <description>Uai host service (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,
+  restart,
+  status,
+};