pi-better-background-tasks 0.2.4 → 0.2.6

package/src/remote-task-preset.ts

@@ -1,5 +1,16 @@
 import { runCommandOnce, spawnCommand } from "./process.js";
 import type { SpawnedProcess } from "./process.js";
+import {
+  createTmuxSessionController,
+  resolveSshCommand,
+} from "./shared-ssh-core/index.js";
+import type {
+  RemoteRunner,
+  TmuxBootstrapOptions,
+  TmuxBootstrapResult,
+  TmuxPackageManager,
+  TmuxSessionPollResult,
+} from "./shared-ssh-core/index.js";
 import type {
   CommandResult,
   CommandSpec,
@@ -9,13 +20,17 @@ import type {
   SshConnectionParams,
 } from "./types.js";
 
-export const DEFAULT_SSH_CONNECT_TIMEOUT_SECONDS = 10;
-export const DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS = 120_000;
-
-export interface RemoteRunner {
-  spawn(spec: CommandSpec, logPath: string, detached: boolean): SpawnedProcess;
-  runOnce(spec: CommandSpec, maxBufferBytes?: number, timeoutMs?: number): Promise<CommandResult>;
-}
+export {
+  DEFAULT_SSH_CONNECT_TIMEOUT_SECONDS,
+  DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS,
+} from "./shared-ssh-core/index.js";
+export type {
+  RemoteRunner,
+  TmuxBootstrapOptions,
+  TmuxBootstrapResult,
+  TmuxPackageManager,
+  TmuxSessionPollResult,
+};
 
 export interface SshRemoteTaskIntent {
   operation: "spawn" | "watch";
@@ -28,68 +43,6 @@ export interface SshRemoteTaskIntent {
   remote?: RemoteTaskParams;
 }
 
-export type TmuxPackageManager = "apt-get" | "dnf" | "yum" | "apk" | "pacman" | "zypper" | "brew";
-
-type TmuxBootstrapCapability = {
-  target: string;
-  tmuxPath: string;
-  tmuxVersion: string;
-  message: string;
-};
-
-type TmuxBootstrapGuidance = {
-  target: string;
-  mutated: boolean;
-  verifyCommand: string;
-  message: string;
-};
-
-export type TmuxBootstrapResult =
-  | (TmuxBootstrapCapability & {
-    status: "present";
-    mutated: false;
-  })
-  | (TmuxBootstrapCapability & {
-    status: "installed";
-    packageManager: TmuxPackageManager;
-    mutated: true;
-    installCommand: string;
-    verifyCommand: string;
-  })
-  | (TmuxBootstrapGuidance & {
-    status: "needs_user";
-    reason: "passwordless_sudo_unavailable" | "install_disabled";
-    packageManager: TmuxPackageManager;
-    mutated: false;
-    installCommand: string;
-  })
-  | (TmuxBootstrapGuidance & {
-    status: "unknown_package_manager";
-    mutated: false;
-  })
-  | (TmuxBootstrapGuidance & {
-    status: "install_failed";
-    packageManager?: TmuxPackageManager;
-    exitCode: number | null;
-    installCommand?: string;
-  })
-  | (TmuxBootstrapGuidance & {
-    status: "timed_out";
-    packageManager?: TmuxPackageManager;
-    installCommand?: string;
-  });
-
-export interface TmuxBootstrapOptions {
-  timeoutMs?: number;
-}
-
-export interface TmuxSessionPollResult {
-  status: "running" | "missing" | "timed_out" | number;
-  logSize: number;
-  output: string;
-  commandResult: CommandResult;
-}
-
 export interface ResolvedSshRemoteTask {
   commandSpec: CommandSpec;
   metadata: {
@@ -108,88 +61,19 @@ const processRemoteRunner: RemoteRunner = {
   spawn: spawnCommand,
   runOnce: runCommandOnce,
 };
-
-const REQUIRED_SSH_OPTIONS = new Set(["batchmode", "connecttimeout", "requesttty"]);
 const DIRECT_STOP_WARNING = "Direct SSH mode has weak stop semantics: stopping the local SSH client may leave the remote process running.";
-const TMUX_STATUS_PREFIX = "__PI_BG_STATUS__=";
-const TMUX_SIZE_PREFIX = "__PI_BG_SIZE__=";
-const TMUX_PATH_PREFIX = "__PI_BG_TMUX_PATH__=";
-const TMUX_VERSION_PREFIX = "__PI_BG_TMUX_VERSION__=";
-const TMUX_CAPTURE_CHUNK_BYTES = 256 * 1024;
-const TMUX_PROBE_COMMAND = [
-  "tmux_path=$(command -v tmux) || exit 127",
-  `printf '${TMUX_PATH_PREFIX}%s\\n' "$tmux_path"`,
-  `printf '${TMUX_VERSION_PREFIX}%s\\n' "$("$tmux_path" -V)"`,
-].join("; ");
-const TMUX_PACKAGE_MANAGERS: TmuxPackageManager[] = ["apt-get", "dnf", "yum", "apk", "pacman", "zypper", "brew"];
-const TMUX_INSTALL_COMMANDS: Record<TmuxPackageManager, string> = {
-  "apt-get": "apt-get update && apt-get install -y tmux",
-  dnf: "dnf install -y tmux",
-  yum: "yum install -y tmux",
-  apk: "apk add --no-cache tmux",
-  pacman: "pacman -Sy --noconfirm tmux",
-  zypper: "zypper --non-interactive install tmux",
-  brew: "brew install tmux",
-};
-const TMUX_DETECT_COMMAND = [
-  "remote_user=$(id -un) || exit 1",
-  "remote_uid=$(id -u) || exit 1",
-  "package_manager=''",
-  `for candidate in ${TMUX_PACKAGE_MANAGERS.join(" ")}; do if command -v \"$candidate\" >/dev/null 2>&1; then package_manager=$candidate; break; fi; done`,
-  "if [ \"$package_manager\" = brew ]; then privilege=direct; elif [ \"$remote_uid\" -eq 0 ]; then privilege=root; elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then privilege=sudo; else privilege=needs_user; fi",
-  "printf 'user=%s\\nuid=%s\\npm=%s\\nprivilege=%s\\n' \"$remote_user\" \"$remote_uid\" \"$package_manager\" \"$privilege\"",
-].join("; ");
 
 export function expandSshRemoteTaskPreset(
   intent: SshRemoteTaskIntent,
   runner: RemoteRunner = processRemoteRunner,
 ): ResolvedSshRemoteTask {
-  const command = requireValue(intent.command, "command is required when ssh is set");
-  const host = requireToken(intent.ssh.host, "ssh.host is required");
-  const user = optionalToken(intent.ssh.user, "ssh.user must not be empty or contain whitespace");
-  const target = user ? `${user}@${host}` : host;
-  const argv = [
-    "ssh",
-    "-o", "BatchMode=yes",
-    "-o", `ConnectTimeout=${DEFAULT_SSH_CONNECT_TIMEOUT_SECONDS}`,
-    "-T",
-  ];
-
-  if (intent.ssh.port !== undefined) {
-    if (!Number.isInteger(intent.ssh.port) || intent.ssh.port < 1 || intent.ssh.port > 65_535) {
-      throw new Error("ssh.port must be an integer between 1 and 65535");
-    }
-    argv.push("-p", String(intent.ssh.port));
-  }
-
-  const identityFile = optionalValue(intent.ssh.identity_file, "ssh.identity_file must not be empty");
-  if (identityFile) argv.push("-i", identityFile);
-  const jump = optionalValue(intent.ssh.jump, "ssh.jump must not be empty");
-  if (jump) argv.push("-J", jump);
-
-  for (const [rawKey, rawValue] of Object.entries(intent.ssh.options ?? {})) {
-    const key = requireToken(rawKey, "ssh option names must not be empty or contain whitespace");
-    if (REQUIRED_SSH_OPTIONS.has(key.toLowerCase())) continue;
-    argv.push("-o", `${key}=${String(rawValue)}`);
-  }
-  argv.push("--", target, command);
-
-  const commandSpec: CommandSpec = {
-    command,
-    argv,
-    shell: false,
+  const resolved = resolveSshCommand({
+    command: intent.command,
     cwd: intent.cwd,
     env: intent.env,
-  };
-  const ssh: ResolvedSshIdentity = {
-    host,
-    ...(user ? { user } : {}),
-    ...(intent.ssh.port !== undefined ? { port: intent.ssh.port } : {}),
-    ...(identityFile ? { identityFile } : {}),
-    ...(jump ? { jump } : {}),
-    ...(intent.ssh.options ? { options: { ...intent.ssh.options } } : {}),
-    target,
-  };
+    ssh: intent.ssh,
+  });
+  const command = resolved.commandSpec.command!;
   const session = intent.operation === "spawn" ? intent.remote?.session ?? "tmux" : "direct";
   const installTmux = intent.operation === "spawn" && session === "tmux"
     ? intent.remote?.install_tmux !== false
@@ -205,441 +89,39 @@ export function expandSshRemoteTaskPreset(
     ...(sessionName ? { sessionName, bootstrapStatus: "pending", sessionStarted: false } : {}),
     ...(session === "direct" && intent.operation === "spawn" ? { warning: DIRECT_STOP_WARNING } : {}),
   };
-
-  const requireSessionName = (): string => {
+  const controller = createTmuxSessionController({
+    ...resolved,
+    runner,
+    sessionName: sessionName ?? "pi-bg-unused",
+    command,
+    workdir: intent.remote?.workdir,
+    installTmux,
+  });
+  const requireTmuxSession = (): void => {
     if (!sessionName) throw new Error("taskId is required for tmux-backed SSH spawn lifecycle operations");
-    return sessionName;
   };
 
   return {
-    commandSpec,
-    metadata: { ssh, remote },
-    bootstrapTmux: async (options) => bootstrapTmux(
-      commandSpec,
-      target,
-      runner,
-      installTmux,
-      resolveBootstrapTimeoutMs(options?.timeoutMs),
-    ),
-    startTmuxSession: (tmuxPath) => runner.runOnce(withRemoteCommand(
-      commandSpec,
-      tmuxStartCommand(tmuxPath, requireSessionName(), command, intent.remote?.workdir),
-    )),
-    pollTmuxSession: async (logOffset, timeoutMs) => parseTmuxPollResult(await runner.runOnce(withRemoteCommand(
-      commandSpec,
-      tmuxPollCommand(requireSessionName(), logOffset),
-    ), undefined, timeoutMs), logOffset),
-    killTmuxSession: () => runner.runOnce(withRemoteCommand(
-      commandSpec,
-      `tmux kill-session -t ${shellQuote(requireSessionName())}`,
-    )),
-    spawn: (logPath, detached) => runner.spawn(commandSpec, logPath, detached),
-    runOnce: (maxBufferBytes, timeoutMs) => runner.runOnce(commandSpec, maxBufferBytes, timeoutMs),
+    commandSpec: resolved.commandSpec,
+    metadata: { ssh: resolved.identity, remote },
+    bootstrapTmux: (options) => controller.bootstrapTmux(options),
+    startTmuxSession: (tmuxPath) => {
+      requireTmuxSession();
+      return controller.startTmuxSession(tmuxPath);
+    },
+    pollTmuxSession: (logOffset, timeoutMs) => {
+      requireTmuxSession();
+      return controller.pollTmuxSession(logOffset, timeoutMs);
+    },
+    killTmuxSession: () => {
+      requireTmuxSession();
+      return controller.killTmuxSession();
+    },
+    spawn: (logPath, detached) => runner.spawn(resolved.commandSpec, logPath, detached),
+    runOnce: (maxBufferBytes, timeoutMs) => runner.runOnce(resolved.commandSpec, maxBufferBytes, timeoutMs),
   };
 }
 
 function sessionNameForTask(taskId: string): string {
   return `pi-bg-${taskId.replaceAll(/[^A-Za-z0-9_-]/g, "-")}`;
 }
-
-function tmuxLogPath(sessionName: string): string {
-  return `/tmp/${sessionName}.log`;
-}
-
-function tmuxExitPath(sessionName: string): string {
-  return `/tmp/${sessionName}.exit`;
-}
-
-function tmuxStartCommand(tmuxPath: string, sessionName: string, command: string, workdir?: string): string {
-  const logPath = tmuxLogPath(sessionName);
-  const exitPath = tmuxExitPath(sessionName);
-  const script = [
-    ...(workdir ? [`cd -- ${shellQuote(workdir)}`] : []),
-    `sh -lc ${shellQuote(command)} >${shellQuote(logPath)} 2>&1`,
-    "exit_code=$?",
-    `printf '%s\\n' "$exit_code" >${shellQuote(exitPath)}`,
-    "exit \"$exit_code\"",
-  ].join("; ");
-  return [
-    `rm -f ${shellQuote(logPath)} ${shellQuote(exitPath)}`,
-    `${shellQuote(tmuxPath)} new-session -d -s ${shellQuote(sessionName)} sh -lc ${shellQuote(script)}`,
-  ].join("; ");
-}
-
-function tmuxPollCommand(sessionName: string, logOffset: number): string {
-  const normalizedOffset = Math.max(0, Math.floor(logOffset));
-  const logPath = tmuxLogPath(sessionName);
-  const exitPath = tmuxExitPath(sessionName);
-  return [
-    "status=running",
-    `if test -f ${shellQuote(exitPath)}; then status=$(cat ${shellQuote(exitPath)}); elif ! tmux has-session -t ${shellQuote(sessionName)} 2>/dev/null; then status=missing; fi`,
-    `size=$(wc -c < ${shellQuote(logPath)} 2>/dev/null || printf '0')`,
-    "size=$(printf '%s' \"$size\" | tr -d '[:space:]')",
-    `next_offset=$(( ${normalizedOffset} + ${TMUX_CAPTURE_CHUNK_BYTES} ))`,
-    "if test \"$next_offset\" -gt \"$size\"; then next_offset=$size; fi",
-    "reported_status=$status",
-    "if test \"$next_offset\" -lt \"$size\"; then reported_status=running; fi",
-    `printf '${TMUX_STATUS_PREFIX}%s\\n${TMUX_SIZE_PREFIX}%s\\n' "$reported_status" "$next_offset"`,
-    `if test "$next_offset" -gt ${normalizedOffset}; then tail -c +${normalizedOffset + 1} ${shellQuote(logPath)} | head -c $(( next_offset - ${normalizedOffset} )); fi`,
-  ].join("; ");
-}
-
-function parseTmuxPollResult(result: CommandResult, logOffset: number): TmuxSessionPollResult {
-  if (result.timedOut) {
-    return {
-      status: "timed_out",
-      logSize: Math.max(0, Math.floor(logOffset)),
-      output: result.stdout,
-      commandResult: result,
-    };
-  }
-  const [statusLine = "", sizeLine = "", ...outputLines] = result.stdout.split("\n");
-  if (!statusLine.startsWith(TMUX_STATUS_PREFIX) || !sizeLine.startsWith(TMUX_SIZE_PREFIX)) {
-    throw new Error(`remote tmux supervision returned an invalid response${result.stderr.trim() ? `: ${result.stderr.trim()}` : ""}`);
-  }
-  const rawStatus = statusLine.slice(TMUX_STATUS_PREFIX.length);
-  const rawSize = sizeLine.slice(TMUX_SIZE_PREFIX.length);
-  const logSize = Number(rawSize);
-  if (!Number.isSafeInteger(logSize) || logSize < 0) {
-    throw new Error(`remote tmux supervision returned invalid log size ${JSON.stringify(rawSize)}`);
-  }
-  const status = rawStatus === "running" || rawStatus === "missing"
-    ? rawStatus
-    : Number(rawStatus);
-  if (typeof status === "number" && !Number.isInteger(status)) {
-    throw new Error(`remote tmux supervision returned invalid status ${JSON.stringify(rawStatus)}`);
-  }
-  return {
-    status,
-    logSize,
-    output: outputLines.join("\n"),
-    commandResult: result,
-  };
-}
-
-async function bootstrapTmux(
-  commandSpec: CommandSpec,
-  target: string,
-  runner: RemoteRunner,
-  installEnabled: boolean,
-  timeoutMs: number,
-): Promise<TmuxBootstrapResult> {
-  const deadlineAt = Date.now() + timeoutMs;
-  let timeoutContext: TmuxBootstrapTimeoutContext = {
-    target,
-    mutated: false,
-    verifyCommand: sshGuidanceCommand(commandSpec, target, "command -v tmux && tmux -V"),
-    stage: "probing tmux",
-  };
-  const run = async (remoteCommand: string): Promise<CommandResult> => {
-    const remainingMs = deadlineAt - Date.now();
-    if (remainingMs <= 0) throw new TmuxBootstrapTimeoutError();
-    const result = await runner.runOnce(withRemoteCommand(commandSpec, remoteCommand), undefined, remainingMs);
-    if (result.timedOut) throw new TmuxBootstrapTimeoutError();
-    return result;
-  };
-
-  try {
-    return await bootstrapTmuxWithinDeadline(run, commandSpec, target, installEnabled, timeoutContext, (context) => {
-      timeoutContext = context;
-    });
-  } catch (error) {
-    if (!(error instanceof TmuxBootstrapTimeoutError)) throw error;
-    const remediation = timeoutContext.installCommand
-      ? `Run: ${timeoutContext.installCommand} Then verify: ${timeoutContext.verifyCommand}`
-      : `Install tmux manually if needed, then verify: ${timeoutContext.verifyCommand}`;
-    return {
-      status: "timed_out",
-      target: timeoutContext.target,
-      ...(timeoutContext.packageManager ? { packageManager: timeoutContext.packageManager } : {}),
-      mutated: timeoutContext.mutated,
-      ...(timeoutContext.installCommand ? { installCommand: timeoutContext.installCommand } : {}),
-      verifyCommand: timeoutContext.verifyCommand,
-      message: `tmux bootstrap timed out on ${timeoutContext.target} while ${timeoutContext.stage}. ${remediation}`,
-    };
-  }
-}
-
-interface TmuxBootstrapTimeoutContext {
-  target: string;
-  packageManager?: TmuxPackageManager;
-  mutated: boolean;
-  installCommand?: string;
-  verifyCommand: string;
-  stage: string;
-}
-
-class TmuxBootstrapTimeoutError extends Error {}
-
-async function bootstrapTmuxWithinDeadline(
-  run: (remoteCommand: string) => Promise<CommandResult>,
-  commandSpec: CommandSpec,
-  target: string,
-  installEnabled: boolean,
-  initialTimeoutContext: TmuxBootstrapTimeoutContext,
-  setTimeoutContext: (context: TmuxBootstrapTimeoutContext) => void,
-): Promise<TmuxBootstrapResult> {
-  setTimeoutContext(initialTimeoutContext);
-  const probe = await run(TMUX_PROBE_COMMAND);
-  const capability = parseTmuxCapability(probe);
-  if (capability) {
-    return {
-      status: "present",
-      target,
-      ...capability,
-      mutated: false,
-      message: `${capability.tmuxVersion} is available at ${capability.tmuxPath} on ${target}.`,
-    };
-  }
-  const initialVerifyCommand = sshGuidanceCommand(commandSpec, target, "command -v tmux && tmux -V");
-  if (probe.exitCode !== 127) {
-    const detail = resultDetail(probe);
-    return {
-      status: "install_failed",
-      target,
-      exitCode: probe.exitCode,
-      mutated: false,
-      verifyCommand: initialVerifyCommand,
-      message: `tmux bootstrap could not probe ${target} (exit ${probe.exitCode ?? "unknown"})${detail ? `: ${detail}` : "."} Install tmux manually if needed, then verify: ${initialVerifyCommand}`,
-    };
-  }
-
-  setTimeoutContext({ ...initialTimeoutContext, stage: "detecting the package manager" });
-  const detection = await run(TMUX_DETECT_COMMAND);
-  if (detection.exitCode !== 0) {
-    const detail = resultDetail(detection);
-    return {
-      status: "install_failed",
-      target,
-      exitCode: detection.exitCode,
-      mutated: false,
-      verifyCommand: initialVerifyCommand,
-      message: `tmux bootstrap could not inspect ${target} for an installer (exit ${detection.exitCode ?? "unknown"})${detail ? `: ${detail}` : "."} Install tmux manually if needed, then verify: ${initialVerifyCommand}`,
-    };
-  }
-  const detected = parseDetection(detection);
-  const guidanceTarget = detected && !target.includes("@") ? `${detected.user}@${target}` : target;
-  const verifyCommand = sshGuidanceCommand(commandSpec, guidanceTarget, "command -v tmux && tmux -V");
-  if (!detected || !isTmuxPackageManager(detected.packageManager)) {
-    return {
-      status: "unknown_package_manager",
-      target: guidanceTarget,
-      mutated: false,
-      verifyCommand,
-      message: `tmux is missing on ${guidanceTarget}, but none of ${formatPackageManagerList()} was found. Install tmux manually, then verify: ${verifyCommand}`,
-    };
-  }
-
-  const packageManager = detected.packageManager;
-  const baseInstallCommand = TMUX_INSTALL_COMMANDS[packageManager];
-  const needsSudo = detected.privilege === "sudo" || detected.privilege === "needs_user";
-  const humanInstallCommand = needsSudo ? withInteractiveSudo(baseInstallCommand) : baseInstallCommand;
-  const installCommand = sshGuidanceCommand(commandSpec, guidanceTarget, humanInstallCommand, needsSudo);
-  if (!installEnabled) {
-    return {
-      status: "needs_user",
-      reason: "install_disabled",
-      target: guidanceTarget,
-      packageManager,
-      mutated: false,
-      installCommand,
-      verifyCommand,
-      message: `Automatic tmux installation is disabled for ${guidanceTarget}. Run: ${installCommand} Then verify: ${verifyCommand}`,
-    };
-  }
-  if (detected.privilege === "needs_user") {
-    return {
-      status: "needs_user",
-      reason: "passwordless_sudo_unavailable",
-      target: guidanceTarget,
-      packageManager,
-      mutated: false,
-      installCommand,
-      verifyCommand,
-      message: `tmux is missing on ${guidanceTarget} and automatic installation cannot use passwordless sudo. Run: ${installCommand} Then verify: ${verifyCommand}`,
-    };
-  }
-
-  const machineInstallCommand = detected.privilege === "sudo"
-    ? withNonInteractiveSudo(baseInstallCommand)
-    : baseInstallCommand;
-  setTimeoutContext({
-    target: guidanceTarget,
-    packageManager,
-    mutated: false,
-    installCommand,
-    verifyCommand,
-    stage: `running the ${packageManager} install`,
-  });
-  const install = await run(machineInstallCommand);
-  if (install.exitCode !== 0) {
-    const detail = resultDetail(install);
-    return {
-      status: "install_failed",
-      target: guidanceTarget,
-      packageManager,
-      exitCode: install.exitCode,
-      mutated: false,
-      installCommand,
-      verifyCommand,
-      message: `Automatic tmux install with ${packageManager} failed on ${guidanceTarget} (exit ${install.exitCode ?? "unknown"})${detail ? `: ${detail}` : "."} Run: ${installCommand} Then verify: ${verifyCommand}`,
-    };
-  }
-
-  setTimeoutContext({
-    target: guidanceTarget,
-    packageManager,
-    mutated: true,
-    installCommand,
-    verifyCommand,
-    stage: "verifying the installed tmux",
-  });
-  const reprobe = await run(TMUX_PROBE_COMMAND);
-  const installedCapability = parseTmuxCapability(reprobe);
-  if (!installedCapability) {
-    return {
-      status: "install_failed",
-      target: guidanceTarget,
-      packageManager,
-      exitCode: reprobe.exitCode,
-      mutated: true,
-      installCommand,
-      verifyCommand,
-      message: `The ${packageManager} install command completed but tmux did not pass verification on ${guidanceTarget}${resultDetail(reprobe) ? `: ${resultDetail(reprobe)}` : "."} Run: ${installCommand} Then verify: ${verifyCommand}`,
-    };
-  }
-  return {
-    status: "installed",
-    target: guidanceTarget,
-    packageManager,
-    ...installedCapability,
-    mutated: true,
-    installCommand,
-    verifyCommand,
-    message: `Installed tmux with ${packageManager} on ${guidanceTarget}; ${installedCapability.tmuxVersion} is available at ${installedCapability.tmuxPath}.`,
-  };
-}
-
-function resolveBootstrapTimeoutMs(timeoutMs: number | undefined): number {
-  if (timeoutMs === undefined) return DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS;
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new Error("tmux bootstrap timeoutMs must be a positive finite number");
-  }
-  return Math.floor(timeoutMs);
-}
-
-function parseTmuxCapability(result: CommandResult): { tmuxPath: string; tmuxVersion: string } | undefined {
-  if (result.exitCode !== 0) return undefined;
-  let tmuxPath: string | undefined;
-  let tmuxVersion: string | undefined;
-  for (const line of result.stdout.split("\n")) {
-    if (line.startsWith(TMUX_PATH_PREFIX)) tmuxPath = line.slice(TMUX_PATH_PREFIX.length);
-    if (line.startsWith(TMUX_VERSION_PREFIX)) tmuxVersion = line.slice(TMUX_VERSION_PREFIX.length);
-  }
-  if (!tmuxPath || !tmuxVersion) return undefined;
-  if (!tmuxPath.startsWith("/") || /\s/.test(tmuxPath)) return undefined;
-  if (!/^tmux\b/i.test(tmuxVersion)) return undefined;
-  return { tmuxPath, tmuxVersion };
-}
-
-interface TmuxDetection {
-  user: string;
-  packageManager: string;
-  privilege: "root" | "sudo" | "direct" | "needs_user";
-}
-
-function parseDetection(result: CommandResult): TmuxDetection | undefined {
-  if (result.exitCode !== 0) return undefined;
-  const values = Object.fromEntries(result.stdout.trim().split("\n").map((line) => {
-    const separator = line.indexOf("=");
-    return separator < 0 ? [line, ""] : [line.slice(0, separator), line.slice(separator + 1)];
-  }));
-  if (!values.user || !/^(root|sudo|direct|needs_user)$/.test(values.privilege ?? "")) return undefined;
-  return {
-    user: values.user,
-    packageManager: values.pm ?? "",
-    privilege: values.privilege as TmuxDetection["privilege"],
-  };
-}
-
-function isTmuxPackageManager(value: string | undefined): value is TmuxPackageManager {
-  return TMUX_PACKAGE_MANAGERS.some((candidate) => candidate === value);
-}
-
-function formatPackageManagerList(): string {
-  return `${TMUX_PACKAGE_MANAGERS.slice(0, -1).join(", ")}, or ${TMUX_PACKAGE_MANAGERS.at(-1)}`;
-}
-
-function resultDetail(result: CommandResult): string {
-  return (result.stderr.trim() || result.stdout.trim()).replaceAll(/\s+/g, " ").slice(0, 500);
-}
-
-function withNonInteractiveSudo(command: string): string {
-  return command.split(" && ").map((part) => `sudo -n ${part}`).join(" && ");
-}
-
-function withInteractiveSudo(command: string): string {
-  return command.split(" && ").map((part) => `sudo ${part}`).join(" && ");
-}
-
-function sshGuidanceCommand(
-  spec: CommandSpec,
-  target: string,
-  remoteCommand: string,
-  tty = false,
-): string {
-  const argv = spec.argv ?? [];
-  const separator = argv.lastIndexOf("--");
-  const connectionArgs: string[] = [];
-  for (let index = 1; index >= 0 && index < separator; index += 1) {
-    const option = argv[index];
-    if (option === "-T") continue;
-    const value = argv[index + 1];
-    if ((option === "-p" || option === "-i" || option === "-J") && value) {
-      connectionArgs.push(option, shellQuote(value));
-      index += 1;
-      continue;
-    }
-    if (option === "-o" && value) {
-      index += 1;
-      const key = value.slice(0, value.indexOf("=")).toLowerCase();
-      if (REQUIRED_SSH_OPTIONS.has(key)) continue;
-      connectionArgs.push(option, shellQuote(value));
-    }
-  }
-  const renderedArgs = connectionArgs.length > 0 ? ` ${connectionArgs.join(" ")}` : "";
-  return `ssh${tty ? " -t" : ""}${renderedArgs} ${shellQuote(target)} ${shellQuote(remoteCommand)}`;
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", `'\"'\"'`)}'`;
-}
-
-function withRemoteCommand(spec: CommandSpec, remoteCommand: string): CommandSpec {
-  return {
-    ...spec,
-    command: remoteCommand,
-    argv: [...(spec.argv?.slice(0, -1) ?? []), remoteCommand],
-  };
-}
-
-function requireValue(value: string | undefined, message: string): string {
-  if (!value || value.trim().length === 0) throw new Error(message);
-  return value;
-}
-
-function requireToken(value: string | undefined, message: string): string {
-  const resolved = requireValue(value, message).trim();
-  if (/\s/.test(resolved)) throw new Error(message);
-  return resolved;
-}
-
-function optionalValue(value: string | undefined, message: string): string | undefined {
-  if (value === undefined) return undefined;
-  return requireValue(value, message);
-}
-
-function optionalToken(value: string | undefined, message: string): string | undefined {
-  if (value === undefined) return undefined;
-  return requireToken(value, message);
-}