@runuai/host 0.9.13 → 0.9.42

package/scripts/install/types.ts

@@ -15,6 +15,15 @@ export interface InstallContext {
   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).
@@ -22,6 +31,20 @@ export interface InstallContext {
   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>;
@@ -29,7 +52,27 @@ export interface Installer {
   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

@@ -5,23 +5,230 @@
  */
 
 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";
 
-export function step(
+export interface StepResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
+
+export type StepExecutor = (
   dryRun: boolean,
   cmd: string,
   args: string[],
-  opts: { ignoreError?: boolean } = {},
-): 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 "";
+    return { status: 0, stdout: "", stderr: "" };
   }
   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 {
+    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 res.stdout ?? "";
+  return result.stdout;
 }
 
 /** Print a unit/plist/xml file's path + contents (dry-run). */

package/scripts/install/win.ts

@@ -125,6 +125,18 @@ export const installer: Installer = {
   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/apple-tunnel-route.ts

@@ -0,0 +1,104 @@
+/**
+ * ADR-106 Apple tunnel routing, extracted from main.ts so its two safety
+ * properties are directly testable: the identity proof and the TCP connect
+ * both happen inside the task's lifecycle slot (a concurrent
+ * taskDown/recreate cannot free and reuse the address between proof and
+ * connection), and a readiness-epoch change during the awaited connect
+ * destroys the socket rather than carrying a dead generation's proof out.
+ */
+
+export interface AppleRouteSocket {
+  connect(port: number, host: string): void;
+  once(event: "connect" | "error", listener: () => void): void;
+  destroy(): void;
+}
+
+export interface AppleTunnelRouteDeps {
+  getTask(taskId: string): { statusMirror: string | null } | undefined;
+  reconstruct(task: unknown): Promise<{
+    inspectRoute?: () => Promise<
+      | { kind: "running"; ipv4Address: string }
+      | { kind: "unavailable" }
+      | { kind: "unknown"; detail: string }
+    >;
+  } | null>;
+  runTaskLifecycle<T>(taskId: string, work: () => Promise<T>): Promise<T>;
+  runtimeProblem(): unknown;
+  readinessEpoch(): number;
+  epochIsCurrent(epoch: number): boolean;
+  poison(detail: string): void;
+  createSocket(): AppleRouteSocket;
+  connectTimeoutMs?: number;
+}
+
+export interface AppleTunnelRouteRequest {
+  taskId: string;
+  target: string;
+  containerPort?: number;
+}
+
+export async function resolveAppleTunnelRoute(
+  request: AppleTunnelRouteRequest,
+  deps: AppleTunnelRouteDeps,
+): Promise<{ host: string; port: number; socket: AppleRouteSocket } | null> {
+  const applePort =
+    request.target === "editor" ? 8080 : request.containerPort;
+  if (!applePort) return null;
+  if (deps.getTask(request.taskId)?.statusMirror !== "running") return null;
+  return deps.runTaskLifecycle(request.taskId, async () => {
+    const current = deps.getTask(request.taskId);
+    if (!current || current.statusMirror !== "running") return null;
+    let route:
+      | { kind: "running"; ipv4Address: string }
+      | { kind: "unavailable" }
+      | { kind: "unknown"; detail: string }
+      | null = null;
+    try {
+      const handle = await deps.reconstruct(current);
+      if (handle === null || handle.inspectRoute === undefined) return null;
+      route = await handle.inspectRoute();
+    } catch {
+      return null;
+    }
+    if (route === null) return null;
+    if (route.kind === "unknown") {
+      // The CLI answered with neither presence nor absence — the same signal
+      // class as a Docker daemon that stopped responding mid-tunnel.
+      deps.poison(route.detail);
+      return null;
+    }
+    if (route.kind !== "running") return null;
+    if (deps.runtimeProblem()) return null;
+    const routeEpoch = deps.readinessEpoch();
+    const upstream = deps.createSocket();
+    const connected = await new Promise<boolean>((resolveConnect) => {
+      let settled = false;
+      const settle = (ok: boolean): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(deadline);
+        resolveConnect(ok);
+      };
+      const deadline = setTimeout(() => {
+        upstream.destroy();
+        settle(false);
+      }, deps.connectTimeoutMs ?? 10_000);
+      deadline.unref?.();
+      upstream.once("connect", () => settle(true));
+      upstream.once("error", () => settle(false));
+      upstream.connect(applePort, route.ipv4Address);
+    });
+    if (
+      !connected ||
+      // The awaited connect is a window: a forced recheck can invalidate the
+      // runtime mid-wait, and a proof from a dead generation must not carry
+      // a live socket out of the slot.
+      !deps.epochIsCurrent(routeEpoch) ||
+      deps.runtimeProblem()
+    ) {
+      upstream.destroy();
+      return null;
+    }
+    return { host: route.ipv4Address, port: applePort, socket: upstream };
+  });
+}