@aria-cli/tools 1.0.9 → 1.0.11

package/src/executors/deploy.ts

@@ -1,1066 +0,0 @@
-/**
- * @aria/tools - Deploy tool executor
- *
- * Deploys ARIA to a remote machine via SSH. Handles OS detection,
- * Node.js installation, repo setup, keypair generation, TLS cert
- * discovery/provisioning, firewall configuration, config writing,
- * daemon startup, and health check.
- */
-
-import { spawn } from "node:child_process";
-import type { ToolContext, ToolResult } from "../types.js";
-import { success, fail } from "./utils.js";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface DeployInput {
-  /** SSH target (e.g. "claude@10.0.0.1") */
-  target: string;
-  /** Git repo URL (default: current origin) */
-  repo_url?: string;
-  /** Branch to deploy (default: main) */
-  branch?: string;
-  /** Arion identity name (default: hostname of target) */
-  arion_name?: string;
-  /** Mesh coordination URL */
-  coordination_url?: string;
-  /** Path to SSH private key */
-  ssh_key_path?: string;
-  /** Git commit hash to checkout after clone (pins exact code version) */
-  commit_hash?: string;
-  /** Verify GPG signature on HEAD commit after checkout */
-  verify_signatures?: boolean;
-}
-
-export interface DeployOutput {
-  success: boolean;
-  host: string;
-  port: number | null;
-  fingerprint: string | null;
-  arionName: string;
-  tlsType: TlsType | null;
-}
-
-export type TlsType = "real-ca" | "letsencrypt" | "private-ca";
-
-export interface OSInfo {
-  os: "linux" | "darwin" | "windows" | "unknown";
-}
-
-export type LinuxDistro = "apt" | "dnf" | "apk";
-
-export type FirewallType = "ufw" | "iptables" | "firewalld" | "windows" | "none";
-
-export interface TlsDiscoveryResult {
-  found: boolean;
-  type?: TlsType;
-  cert?: string;
-  key?: string;
-}
-
-// ============================================================================
-// Pure Helper Functions (exported for testing)
-// ============================================================================
-
-/**
- * Detect OS type from `uname -s` output.
- */
-export function detectOS(unameOutput: string): OSInfo {
-  const trimmed = unameOutput.trim();
-  if (!trimmed || trimmed === "UNKNOWN") {
-    return { os: "unknown" };
-  }
-  if (trimmed === "Linux") {
-    return { os: "linux" };
-  }
-  if (trimmed === "Darwin") {
-    return { os: "darwin" };
-  }
-  // MINGW, MSYS, CYGWIN, or Windows-style output
-  if (/^(MINGW|MSYS|CYGWIN)/i.test(trimmed) || /windows/i.test(trimmed)) {
-    return { os: "windows" };
-  }
-  return { os: "unknown" };
-}
-
-/**
- * Detect Linux distribution from /etc/os-release content.
- * Returns the package manager type to use.
- */
-export function detectLinuxDistro(osReleaseContent: string): LinuxDistro {
-  const lower = osReleaseContent.toLowerCase();
-
-  // Extract ID and ID_LIKE fields
-  const idMatch = lower.match(/^id=(.+)$/m);
-  const idLikeMatch = lower.match(/^id_like=(.+)$/m);
-  const id = idMatch?.[1]?.replace(/"/g, "").trim() ?? "";
-  const idLike = idLikeMatch?.[1]?.replace(/"/g, "").trim() ?? "";
-
-  // Alpine
-  if (id === "alpine") {
-    return "apk";
-  }
-
-  // Debian/Ubuntu family
-  if (
-    id === "debian" ||
-    id === "ubuntu" ||
-    idLike.includes("debian") ||
-    idLike.includes("ubuntu")
-  ) {
-    return "apt";
-  }
-
-  // RHEL/Fedora/CentOS/Amazon Linux family
-  if (
-    id === "fedora" ||
-    id === "rhel" ||
-    id === "centos" ||
-    id === "amzn" ||
-    id === "rocky" ||
-    id === "almalinux" ||
-    idLike.includes("fedora") ||
-    idLike.includes("rhel") ||
-    idLike.includes("centos") ||
-    idLike.includes("suse")
-  ) {
-    return "dnf";
-  }
-
-  // Default to apt (nvm-based install works universally)
-  return "apt";
-}
-
-/**
- * Get the shell command to install Node.js for a given OS and distro.
- */
-export function getNodeInstallCommand(osInfo: OSInfo, distro: LinuxDistro): string {
-  switch (osInfo.os) {
-    case "linux":
-      switch (distro) {
-        case "apk":
-          return "apk add --no-cache nodejs npm";
-        case "dnf":
-          return "dnf module install -y nodejs:22 || dnf install -y nodejs";
-        case "apt":
-        default:
-          return (
-            "curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && " +
-            'export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && nvm install 22'
-          );
-      }
-
-    case "darwin":
-      return (
-        "command -v brew >/dev/null && brew install node@22 || " +
-        "{ curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && " +
-        'export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && nvm install 22; }'
-      );
-
-    case "windows":
-      return "winget install --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements";
-
-    default:
-      throw new Error(`Unsupported OS: ${osInfo.os}. Deploy supports Linux, macOS, and Windows.`);
-  }
-}
-
-/**
- * Generate firewall commands to open ARIA ports (443/tcp + 51820/udp).
- */
-export function getFirewallCommands(firewallType: FirewallType): string {
-  switch (firewallType) {
-    case "ufw":
-      return "ufw allow 443/tcp && ufw allow 51820/udp";
-
-    case "iptables":
-      return (
-        "iptables -A INPUT -p tcp --dport 443 -j ACCEPT && " +
-        "iptables -A INPUT -p udp --dport 51820 -j ACCEPT"
-      );
-
-    case "firewalld":
-      return (
-        "firewall-cmd --permanent --add-port=443/tcp && " +
-        "firewall-cmd --permanent --add-port=51820/udp && " +
-        "firewall-cmd --reload"
-      );
-
-    case "windows":
-      return (
-        'netsh advfirewall firewall add rule name="ARIA HTTPS" dir=in action=allow protocol=tcp localport=443 && ' +
-        'netsh advfirewall firewall add rule name="ARIA WireGuard" dir=in action=allow protocol=udp localport=51820'
-      );
-
-    case "none":
-      return "";
-  }
-}
-
-/**
- * Parse TLS cert discovery output from the remote host.
- * The discovery script outputs JSON: { found, type?, cert?, key? }
- */
-export function discoverTlsCerts(sshOutput: string): TlsDiscoveryResult {
-  if (!sshOutput || !sshOutput.trim()) {
-    return { found: false };
-  }
-  try {
-    const data = JSON.parse(sshOutput.trim());
-    if (data.found === true && data.cert && data.key) {
-      return {
-        found: true,
-        type: data.type as TlsType,
-        cert: data.cert,
-        key: data.key,
-      };
-    }
-    return { found: false };
-  } catch {
-    return { found: false };
-  }
-}
-
-/**
- * Build the config JSON object for ~/.aria/config.json.
- */
-export function buildConfigJson(params: {
-  arionName: string;
-  coordinationUrl?: string;
-  tlsCert?: string;
-  tlsKey?: string;
-}): Record<string, unknown> {
-  const config: Record<string, unknown> = {
-    arion_name: params.arionName,
-  };
-  if (params.coordinationUrl) {
-    config.coordination_url = params.coordinationUrl;
-  }
-  if (params.tlsCert && params.tlsKey) {
-    config.tls = {
-      cert: params.tlsCert,
-      key: params.tlsKey,
-    };
-  }
-  return config;
-}
-
-/**
- * Construct the health check URL for the deployed daemon.
- */
-export function buildHealthCheckUrl(host: string, port?: number): string {
-  const p = port ?? 443;
-  return `https://${host}:${p}/api/v1/network/peers`;
-}
-
-function buildRemoteRuntimePidLookupCommand(repoDir: string): string {
-  return `
-    export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-    cd ${repoDir} && node --input-type=module <<'NODE'
-import { resolveOrCreateNode, resolveRuntimeRootDirectory, readRuntimeOwnerRecord } from "./packages/server/dist/index.js";
-const ariaHome = process.env.ARIA_HOME || (process.env.HOME + "/.aria");
-const resolved = await resolveOrCreateNode({ ariaHome });
-const record = readRuntimeOwnerRecord(resolveRuntimeRootDirectory(), resolved.nodeId);
-if (record?.runtimePid) {
-  console.log(String(record.runtimePid));
-}
-NODE
-  `;
-}
-
-function buildRemoteRuntimeStatusLookupCommand(repoDir: string): string {
-  return `
-    export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-    cd ${repoDir} && node --input-type=module <<'NODE'
-import { createRuntimeSocketLocalControlClient } from "./packages/tools/dist/index.js";
-import { resolveOrCreateNode, resolveRuntimeRootDirectory, readRuntimeOwnerRecord } from "./packages/server/dist/index.js";
-const ariaHome = process.env.ARIA_HOME || (process.env.HOME + "/.aria");
-const resolved = await resolveOrCreateNode({ ariaHome });
-const record = readRuntimeOwnerRecord(resolveRuntimeRootDirectory(), resolved.nodeId);
-if (!record?.runtimeSocket) {
-  process.exit(1);
-}
-const client = createRuntimeSocketLocalControlClient({ runtimeSocket: record.runtimeSocket });
-const status = await client.getRuntimeStatus();
-console.log(JSON.stringify(status));
-NODE
-  `;
-}
-
-// ============================================================================
-// Input Validators (A1 — prevent shell injection)
-// ============================================================================
-
-/**
- * Validate git repo URL — must be HTTPS with no shell metacharacters.
- */
-export function validateRepoUrl(url: string): string | null {
-  if (!url) return null;
-  if (!/^https?:\/\/[a-zA-Z0-9.-]+\/[a-zA-Z0-9_.\/-]+(?:\.git)?$/.test(url)) {
-    return "Invalid repo URL format. Use 'https://host/org/repo.git'.";
-  }
-  return null;
-}
-
-/**
- * Validate branch name — alphanumeric, dots, slashes, hyphens, underscores.
- * Rejects shell metacharacters and path traversal.
- */
-export function validateBranch(branch: string): string | null {
-  if (!branch) return null;
-  if (!/^[a-zA-Z0-9_.\/-]+$/.test(branch) || branch.includes("..")) {
-    return "Invalid branch name. Alphanumeric, dots, slashes, hyphens only.";
-  }
-  return null;
-}
-
-/**
- * Validate arion name — alphanumeric, underscores, hyphens only.
- */
-export function validateArionName(name: string): string | null {
-  if (!name) return null;
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    return "Invalid arion name. Alphanumeric, underscores, hyphens only.";
-  }
-  return null;
-}
-
-/**
- * Validate SSH key path — reject traversal and shell metacharacters.
- */
-export function validateSshKeyPath(keyPath: string): string | null {
-  if (!keyPath) return null;
-  if (keyPath.includes("..") || /[;|&`$(){}!<>]/.test(keyPath)) {
-    return "Invalid SSH key path. No traversal or shell metacharacters.";
-  }
-  return null;
-}
-
-/**
- * Validate git commit hash — must be 7-64 lowercase hex characters.
- * Rejects non-hex, too-short, and shell injection attempts.
- */
-export function validateCommitHash(hash: string): string | null {
-  if (!hash) return null;
-  if (!/^[a-f0-9]{7,64}$/.test(hash)) {
-    return "Invalid commit hash. Must be 7-64 lowercase hex characters.";
-  }
-  return null;
-}
-
-/**
- * Pinned pnpm version — matches packageManager field in root package.json.
- * Prevents unpinned `pnpm@latest` from pulling a compromised version.
- */
-export const PINNED_PNPM_VERSION = "10.28.2";
-
-// ============================================================================
-// Rollback Mechanism (A2)
-// ============================================================================
-
-/**
- * Represents a mutating deploy step that can be undone.
- */
-export interface DeployStep {
-  /** Human-readable step name */
-  name: string;
-  /** Shell command to reverse this step (empty string = not reversible) */
-  undoCmd: string;
-}
-
-/**
- * Get firewall undo commands to reverse port-opening rules.
- */
-export function getFirewallUndoCommands(firewallType: FirewallType): string {
-  switch (firewallType) {
-    case "ufw":
-      return "ufw delete allow 443/tcp && ufw delete allow 51820/udp";
-
-    case "iptables":
-      return (
-        "iptables -D INPUT -p tcp --dport 443 -j ACCEPT && " +
-        "iptables -D INPUT -p udp --dport 51820 -j ACCEPT"
-      );
-
-    case "firewalld":
-      return (
-        "firewall-cmd --permanent --remove-port=443/tcp && " +
-        "firewall-cmd --permanent --remove-port=51820/udp && " +
-        "firewall-cmd --reload"
-      );
-
-    case "windows":
-      return (
-        'netsh advfirewall firewall delete rule name="ARIA HTTPS" && ' +
-        'netsh advfirewall firewall delete rule name="ARIA WireGuard"'
-      );
-
-    case "none":
-      return "";
-  }
-}
-
-/**
- * Build rollback commands from recorded deploy steps.
- * Returns commands in reverse order (last step undone first).
- * Skips steps with empty undoCmd.
- */
-export function buildRollbackCommands(steps: DeployStep[]): string[] {
-  return steps
-    .filter((s) => s.undoCmd.length > 0)
-    .reverse()
-    .map((s) => s.undoCmd);
-}
-
-// ============================================================================
-// Idempotency — Deep Merge Config (A3)
-// ============================================================================
-
-/**
- * Deep-merge two config objects. Preserves nested objects from existing config
- * while applying updates. Does not mutate inputs.
- */
-export function deepMergeConfig(
-  existing: Record<string, unknown>,
-  update: Record<string, unknown>,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  // Copy all existing keys
-  for (const key of Object.keys(existing)) {
-    const val = existing[key];
-    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
-      result[key] = { ...(val as Record<string, unknown>) };
-    } else {
-      result[key] = val;
-    }
-  }
-
-  // Apply updates
-  for (const key of Object.keys(update)) {
-    const updateVal = update[key];
-    const existingVal = result[key];
-
-    if (
-      updateVal !== null &&
-      typeof updateVal === "object" &&
-      !Array.isArray(updateVal) &&
-      existingVal !== null &&
-      typeof existingVal === "object" &&
-      !Array.isArray(existingVal)
-    ) {
-      // Recursive merge for nested objects
-      result[key] = deepMergeConfig(
-        existingVal as Record<string, unknown>,
-        updateVal as Record<string, unknown>,
-      );
-    } else {
-      result[key] = updateVal;
-    }
-  }
-
-  return result;
-}
-
-// ============================================================================
-// Key Permissions (A3)
-// ============================================================================
-
-/**
- * Get chmod commands to restrict key and config file permissions to owner-only.
- */
-export function getKeyPermissionCommands(): string {
-  return "chmod 600 ~/.aria/signing-key.json && chmod 600 ~/.aria/config.json";
-}
-
-// ============================================================================
-// SSH Helper
-// ============================================================================
-
-/**
- * Validate SSH target format — prevent command injection.
- */
-function validateTarget(target: string): string | null {
-  if (!target) {
-    return "target is required (e.g. 'user@host')";
-  }
-  // Block shell metacharacters that could enable injection
-  if (/[;|&`$(){}!<>\s]/.test(target)) {
-    return "Invalid target format. Use 'user@host' or 'hostname'.";
-  }
-  return null;
-}
-
-/**
- * Execute a command on the remote host via SSH.
- * Returns { stdout, stderr, exitCode }.
- */
-export function sshExec(
-  target: string,
-  command: string,
-  options?: { sshKeyPath?: string; timeoutMs?: number; abortSignal?: AbortSignal },
-): Promise<{ stdout: string; stderr: string; exitCode: number }> {
-  return new Promise((resolve, reject) => {
-    const args: string[] = [
-      "-o",
-      "StrictHostKeyChecking=accept-new",
-      "-o",
-      "ConnectTimeout=10",
-      "-o",
-      "BatchMode=yes",
-    ];
-    if (options?.sshKeyPath) {
-      args.push("-i", options.sshKeyPath);
-    }
-    args.push(target, command);
-
-    const child = spawn("ssh", args, {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    let stdout = "";
-    let stderr = "";
-
-    child.stdout.on("data", (data: Buffer) => {
-      stdout += data.toString();
-    });
-    child.stderr.on("data", (data: Buffer) => {
-      stderr += data.toString();
-    });
-
-    const timeoutMs = options?.timeoutMs ?? 120_000;
-    const timer = setTimeout(() => {
-      child.kill("SIGTERM");
-      reject(new Error(`SSH command timed out after ${timeoutMs}ms: ${command}`));
-    }, timeoutMs);
-
-    if (options?.abortSignal) {
-      options.abortSignal.addEventListener(
-        "abort",
-        () => {
-          child.kill("SIGTERM");
-          clearTimeout(timer);
-          reject(new Error("SSH command aborted"));
-        },
-        { once: true },
-      );
-    }
-
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 1 });
-    });
-
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
-  });
-}
-
-// ============================================================================
-// TLS Discovery Script (run on remote host)
-// ============================================================================
-
-const TLS_DISCOVERY_SCRIPT = `
-node -e "
-  const fs = require('fs');
-  const path = require('path');
-
-  // Check Let's Encrypt first
-  const leDirs = ['/etc/letsencrypt/live'];
-  for (const dir of leDirs) {
-    try {
-      const domains = fs.readdirSync(dir).filter(d => !d.startsWith('.'));
-      for (const domain of domains) {
-        const cert = path.join(dir, domain, 'fullchain.pem');
-        const key = path.join(dir, domain, 'privkey.pem');
-        if (fs.existsSync(cert) && fs.existsSync(key)) {
-          console.log(JSON.stringify({ found: true, type: 'letsencrypt', cert, key }));
-          process.exit(0);
-        }
-      }
-    } catch {}
-  }
-
-  // Check standard SSL locations
-  const sslPairs = [
-    ['/etc/ssl/certs/server.crt', '/etc/ssl/private/server.key'],
-    ['/etc/ssl/certs/aria.crt', '/etc/ssl/private/aria.key'],
-  ];
-  for (const [cert, key] of sslPairs) {
-    if (fs.existsSync(cert) && fs.existsSync(key)) {
-      console.log(JSON.stringify({ found: true, type: 'real-ca', cert, key }));
-      process.exit(0);
-    }
-  }
-
-  console.log(JSON.stringify({ found: false }));
-"
-`;
-
-// ============================================================================
-// Firewall Detection Script (run on remote host)
-// ============================================================================
-
-const FIREWALL_DETECT_SCRIPT = `
-if command -v ufw >/dev/null 2>&1; then echo "ufw"
-elif command -v firewall-cmd >/dev/null 2>&1; then echo "firewalld"
-elif command -v iptables >/dev/null 2>&1; then echo "iptables"
-else echo "none"
-fi
-`;
-
-// ============================================================================
-// Deploy Executor
-// ============================================================================
-
-/**
- * Deploy ARIA to a remote machine via SSH.
- *
- * Steps:
- * 1. SSH connectivity check
- * 2. OS detection (uname -s)
- * 3. Linux distro detection (for package manager selection)
- * 4. Install Node.js 20+ if missing
- * 5. Enable corepack + pnpm
- * 6. Clone or update repo
- * 7. pnpm install && pnpm build
- * 8. Generate Ed25519 signing keypair if not present
- * 9. TLS cert discovery + optional provisioning
- * 10. Firewall port opening (443/tcp + 51820/udp)
- * 11. Write ~/.aria/config.json
- * 12. Start daemon on port 443
- * 13. Health check (curl endpoint)
- */
-export async function executeDeploy(input: DeployInput, ctx: ToolContext): Promise<ToolResult> {
-  // Validate all inputs before any SSH calls (A1 — prevent shell injection)
-  const targetError = validateTarget(input.target);
-  if (targetError) {
-    return fail(targetError);
-  }
-  const repoErr = validateRepoUrl(input.repo_url ?? "");
-  if (repoErr) return fail(repoErr);
-  const branchErr = validateBranch(input.branch ?? "");
-  if (branchErr) return fail(branchErr);
-  const nameErr = validateArionName(input.arion_name ?? "");
-  if (nameErr) return fail(nameErr);
-  const keyErr = validateSshKeyPath(input.ssh_key_path ?? "");
-  if (keyErr) return fail(keyErr);
-  const hashErr = validateCommitHash(input.commit_hash ?? "");
-  if (hashErr) return fail(hashErr);
-
-  const sshOpts = { sshKeyPath: input.ssh_key_path, abortSignal: ctx.abortSignal };
-  const branch = input.branch ?? "main";
-  const repoUrl = input.repo_url ?? "https://github.com/aria-ai/aria.git";
-
-  // Request user confirmation — this is a dangerous operation
-  const confirmed = await ctx.confirm(
-    `Deploy ARIA to ${input.target}? This will install Node.js, clone the repo, build, and start the daemon.`,
-  );
-  if (!confirmed) {
-    return fail("User cancelled deployment");
-  }
-
-  // Track mutating steps for rollback on failure (A2)
-  const completedSteps: DeployStep[] = [];
-  let deployFailed = false;
-
-  try {
-    // Step 1: SSH connectivity check
-    const connectivity = await sshExec(input.target, "echo ARIA_SSH_OK", sshOpts);
-    if (connectivity.exitCode !== 0 || !connectivity.stdout.includes("ARIA_SSH_OK")) {
-      return fail(
-        `SSH connectivity failed to ${input.target}: ${connectivity.stderr || "no response"}`,
-      );
-    }
-
-    // Step 2: Detect OS
-    const osResult = await sshExec(input.target, "uname -s 2>/dev/null || echo UNKNOWN", sshOpts);
-    const osInfo = detectOS(osResult.stdout);
-
-    if (osInfo.os === "unknown") {
-      return fail(`Unsupported OS detected from uname: ${osResult.stdout.trim()}`);
-    }
-
-    // Step 3: Detect Linux distro for package manager selection
-    let distro: LinuxDistro = "apt";
-    if (osInfo.os === "linux") {
-      const distroResult = await sshExec(
-        input.target,
-        "cat /etc/os-release 2>/dev/null || echo ''",
-        sshOpts,
-      );
-      distro = detectLinuxDistro(distroResult.stdout);
-    }
-
-    // Step 4: Install Node.js 20+ if not present
-    const nodeCheck = await sshExec(
-      input.target,
-      'node --version 2>/dev/null || echo "NO_NODE"',
-      sshOpts,
-    );
-    const hasNode =
-      nodeCheck.stdout.startsWith("v") && parseInt(nodeCheck.stdout.slice(1), 10) >= 20;
-
-    if (!hasNode) {
-      const installCmd = getNodeInstallCommand(osInfo, distro);
-      const installResult = await sshExec(input.target, installCmd, {
-        ...sshOpts,
-        timeoutMs: 300_000,
-      });
-      if (installResult.exitCode !== 0) {
-        return fail(`Node.js installation failed: ${installResult.stderr}`);
-      }
-    }
-
-    // Step 5: Enable corepack + pnpm (pinned version — never use @latest)
-    const corepackCmd = `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; corepack enable && corepack prepare pnpm@${PINNED_PNPM_VERSION} --activate`;
-    const corepackResult = await sshExec(input.target, corepackCmd, sshOpts);
-    if (corepackResult.exitCode !== 0) {
-      return fail(`corepack/pnpm setup failed: ${corepackResult.stderr}`);
-    }
-
-    // Step 6: Clone or update repo
-    const repoDir = "~/aria";
-    const cloneCmd = `
-      export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-      if [ -d ${repoDir}/.git ]; then
-        cd ${repoDir} && git fetch origin && git checkout ${branch} && git pull origin ${branch}
-      else
-        git clone --branch ${branch} ${repoUrl} ${repoDir}
-      fi
-    `;
-    const cloneResult = await sshExec(input.target, cloneCmd, {
-      ...sshOpts,
-      timeoutMs: 180_000,
-    });
-    if (cloneResult.exitCode !== 0) {
-      return fail(`Repo clone/update failed: ${cloneResult.stderr}`);
-    }
-
-    // Step 6b: Pin to exact commit hash if provided (prevents MITM on branch refs)
-    if (input.commit_hash) {
-      const checkoutResult = await sshExec(
-        input.target,
-        `cd ${repoDir} && git checkout ${input.commit_hash}`,
-        sshOpts,
-      );
-      if (checkoutResult.exitCode !== 0) {
-        return fail(`Commit hash checkout failed: ${checkoutResult.stderr}`);
-      }
-    }
-
-    // Step 6c: Verify GPG signature on HEAD if requested
-    if (input.verify_signatures) {
-      const gpgResult = await sshExec(
-        input.target,
-        `cd ${repoDir} && git verify-commit HEAD`,
-        sshOpts,
-      );
-      if (gpgResult.exitCode !== 0) {
-        return fail(
-          `GPG signature verification failed: ${gpgResult.stderr}. ` +
-            `Set verify_signatures=false to skip.`,
-        );
-      }
-    }
-
-    // Step 7: pnpm install && pnpm build
-    const buildCmd = `
-      export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-      cd ${repoDir} && pnpm install --frozen-lockfile && pnpm store verify && pnpm build
-    `;
-    const buildResult = await sshExec(input.target, buildCmd, {
-      ...sshOpts,
-      timeoutMs: 600_000,
-    });
-    if (buildResult.exitCode !== 0) {
-      return fail(`Build failed: ${buildResult.stderr}`);
-    }
-
-    // Step 8: Generate Ed25519 signing keypair if not present
-    const keypairCmd = `
-      mkdir -p ~/.aria
-      if [ ! -f ~/.aria/signing-key.json ]; then
-        node -e "
-          const crypto = require('crypto');
-          const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-          const pub = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
-          const priv = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64');
-          const fp = crypto.createHash('sha256').update(Buffer.from(pub, 'base64')).digest('hex');
-          const data = JSON.stringify({ publicKey: pub, privateKey: priv, fingerprint: fp }, null, 2);
-          require('fs').writeFileSync(process.env.HOME + '/.aria/signing-key.json', data, { mode: 0o600 });
-          console.log(JSON.stringify({ publicKey: pub, fingerprint: fp }));
-        "
-      else
-        node -e "
-          const data = JSON.parse(require('fs').readFileSync(process.env.HOME + '/.aria/signing-key.json', 'utf8'));
-          console.log(JSON.stringify({ publicKey: data.publicKey, fingerprint: data.fingerprint }));
-        "
-      fi
-    `;
-    const keypairResult = await sshExec(input.target, keypairCmd, sshOpts);
-    if (keypairResult.exitCode !== 0) {
-      return fail(`Keypair generation failed: ${keypairResult.stderr}`);
-    }
-    completedSteps.push({ name: "keypair", undoCmd: "" }); // keypair is not rolled back (idempotent)
-
-    // A3: Set key file permissions (chmod 600)
-    const chmodKeyResult = await sshExec(
-      input.target,
-      "chmod 600 ~/.aria/signing-key.json",
-      sshOpts,
-    );
-    if (chmodKeyResult.exitCode !== 0) {
-      // Non-fatal — best effort
-    }
-
-    let fingerprint: string | null = null;
-    try {
-      const keypairData = JSON.parse(keypairResult.stdout);
-      fingerprint = keypairData.fingerprint ?? null;
-    } catch {
-      // Non-fatal — fingerprint is informational
-    }
-
-    // Step 9: TLS cert discovery + optional provisioning
-    const tlsResult = await sshExec(input.target, TLS_DISCOVERY_SCRIPT, sshOpts);
-    let tlsInfo = discoverTlsCerts(tlsResult.stdout);
-    let tlsType: TlsType | null = null;
-
-    if (tlsInfo.found && tlsInfo.type) {
-      tlsType = tlsInfo.type;
-    } else {
-      // Try Let's Encrypt auto-provisioning
-      const hostnameResult = await sshExec(
-        input.target,
-        "hostname -f 2>/dev/null || hostname",
-        sshOpts,
-      );
-      const hostname = hostnameResult.stdout.trim();
-
-      // Only attempt certbot if we have a domain name (not just an IP)
-      if (hostname && !/^[\d.]+$/.test(hostname) && !/^[\da-f:]+$/i.test(hostname)) {
-        const certbotResult = await sshExec(
-          input.target,
-          `command -v certbot >/dev/null 2>&1 && certbot certonly --standalone -d ${hostname} --non-interactive --agree-tos --register-unsafely-without-email 2>&1 || echo "NO_CERTBOT"`,
-          { ...sshOpts, timeoutMs: 120_000 },
-        );
-        if (certbotResult.exitCode === 0 && !certbotResult.stdout.includes("NO_CERTBOT")) {
-          tlsInfo = {
-            found: true,
-            type: "letsencrypt",
-            cert: `/etc/letsencrypt/live/${hostname}/fullchain.pem`,
-            key: `/etc/letsencrypt/live/${hostname}/privkey.pem`,
-          };
-          tlsType = "letsencrypt";
-        }
-      }
-
-      // Fall back to ARIA private CA
-      if (!tlsType) {
-        const privateCaCmd = `
-          export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-          cd ~/aria && node -e "
-            const { ensureMeshCerts } = require('./packages/server/dist/tls/mesh-certs.js');
-            ensureMeshCerts().then(r => console.log(JSON.stringify({ cert: r.certPath, key: r.keyPath })));
-          " 2>/dev/null || echo '{"cert":"~/.aria/tls/server.crt","key":"~/.aria/tls/server.key"}'
-        `;
-        const privateCaResult = await sshExec(input.target, privateCaCmd, sshOpts);
-        try {
-          const caPaths = JSON.parse(privateCaResult.stdout);
-          tlsInfo = {
-            found: true,
-            type: "private-ca",
-            cert: caPaths.cert,
-            key: caPaths.key,
-          };
-          tlsType = "private-ca";
-        } catch {
-          // TLS setup failed, proceed without — daemon may still start on HTTP
-        }
-      }
-    }
-
-    // Step 10: Firewall port opening (A2 — tracked for rollback)
-    let firewallType: FirewallType = "none";
-    if (osInfo.os === "linux") {
-      const fwDetect = await sshExec(input.target, FIREWALL_DETECT_SCRIPT, sshOpts);
-      firewallType = fwDetect.stdout.trim() as FirewallType;
-      const fwCmds = getFirewallCommands(firewallType);
-      if (fwCmds) {
-        const fwResult = await sshExec(input.target, fwCmds, sshOpts);
-        if (fwResult.exitCode === 0) {
-          completedSteps.push({
-            name: "firewall",
-            undoCmd: getFirewallUndoCommands(firewallType),
-          });
-        }
-        // Best-effort — don't fail the deploy if firewall commands fail (may need sudo)
-      }
-    }
-
-    // Derive arion name from target hostname if not provided
-    const host = input.target.includes("@") ? input.target.split("@")[1]! : input.target;
-    const arionName = input.arion_name ?? host.replace(/[^a-zA-Z0-9-]/g, "-");
-
-    // Step 11: Write ~/.aria/config.json (A3 — deep merge for idempotency)
-    const configObj = buildConfigJson({
-      arionName,
-      coordinationUrl: input.coordination_url,
-      tlsCert: tlsInfo.found ? tlsInfo.cert : undefined,
-      tlsKey: tlsInfo.found ? tlsInfo.key : undefined,
-    });
-    const configJson = JSON.stringify(configObj);
-    // Escape for shell — replace single quotes
-    const escapedConfig = configJson.replace(/'/g, "'\\''");
-    const configCmd = `
-      mkdir -p ~/.aria
-      if [ -f ~/.aria/config.json ]; then
-        node -e "
-          const fs = require('fs');
-          const existing = JSON.parse(fs.readFileSync(process.env.HOME + '/.aria/config.json', 'utf8'));
-          const updates = JSON.parse('${escapedConfig}');
-          // Deep merge: preserve nested objects
-          function deepMerge(target, source) {
-            for (const key of Object.keys(source)) {
-              if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) &&
-                  target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])) {
-                deepMerge(target[key], source[key]);
-              } else {
-                target[key] = source[key];
-              }
-            }
-            return target;
-          }
-          deepMerge(existing, updates);
-          fs.writeFileSync(process.env.HOME + '/.aria/config.json', JSON.stringify(existing, null, 2), { mode: 0o600 });
-        "
-      else
-        echo '${escapedConfig}' > ~/.aria/config.json && chmod 600 ~/.aria/config.json
-      fi
-    `;
-    const configResult = await sshExec(input.target, configCmd, sshOpts);
-    if (configResult.exitCode !== 0) {
-      deployFailed = true;
-      return fail(`Config write failed: ${configResult.stderr}`);
-    }
-    completedSteps.push({ name: "config", undoCmd: "rm -f ~/.aria/config.json" });
-
-    // A3: Set config file permissions (chmod 600)
-    await sshExec(input.target, "chmod 600 ~/.aria/config.json", sshOpts);
-
-    // Step 12: Start daemon (nohup, backgrounded) on port 443
-    const runtimePidLookupCmd = buildRemoteRuntimePidLookupCommand(repoDir);
-    const runtimeStatusLookupCmd = buildRemoteRuntimeStatusLookupCommand(repoDir);
-    const daemonCmd = `
-      # Kill existing daemon if running
-      PID=$(${runtimePidLookupCmd} 2>/dev/null || true)
-      [ -n "$PID" ] && kill "$PID" 2>/dev/null || true
-      export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-      cd ${repoDir}
-      nohup node packages/cli/bin/aria.js daemon --arion ${arionName} --port 443 > ~/.aria/daemon.log 2>&1 &
-      echo $!
-    `;
-    const daemonResult = await sshExec(input.target, daemonCmd, sshOpts);
-    if (daemonResult.exitCode !== 0) {
-      deployFailed = true;
-      return fail(`Daemon start failed: ${daemonResult.stderr}`);
-    }
-    completedSteps.push({
-      name: "daemon",
-      undoCmd: `PID=$(${runtimePidLookupCmd} 2>/dev/null || true); [ -n "$PID" ] && kill "$PID" 2>/dev/null || true`,
-    });
-
-    // Step 13: Health check — wait for runtime owner/socket status then verify endpoint (A3 — mandatory)
-    const healthCmd = `
-      for i in $(seq 1 15); do
-        STATUS=$(${runtimeStatusLookupCmd} 2>/dev/null || true)
-        if [ -n "$STATUS" ]; then
-          echo "$STATUS"
-          exit 0
-        fi
-        sleep 1
-      done
-      echo "TIMEOUT"
-      exit 1
-    `;
-    const healthResult = await sshExec(input.target, healthCmd, {
-      ...sshOpts,
-      timeoutMs: 30_000,
-    });
-
-    let port: number | null = null;
-    if (healthResult.exitCode === 0 && !healthResult.stdout.includes("TIMEOUT")) {
-      try {
-        const runtimeStatus = JSON.parse(healthResult.stdout);
-        port = runtimeStatus.port ?? null;
-      } catch {
-        // Non-fatal
-      }
-    }
-
-    // A3: Mandatory health check — verify HTTP(S) endpoint returns 2xx
-    if (port) {
-      const healthUrl = buildHealthCheckUrl(host, port);
-      const curlCmd = `curl -sSk -o /dev/null -w "%{http_code}" ${healthUrl} 2>/dev/null || echo "000"`;
-      const curlResult = await sshExec(input.target, curlCmd, {
-        ...sshOpts,
-        timeoutMs: 10_000,
-      });
-      const httpCode = parseInt(curlResult.stdout.trim(), 10);
-      if (isNaN(httpCode) || httpCode < 200 || httpCode >= 300) {
-        deployFailed = true;
-        return fail(
-          `Health check failed: ${healthUrl} returned HTTP ${curlResult.stdout.trim()}. ` +
-            `Check ~/.aria/daemon.log on ${input.target}.`,
-        );
-      }
-    } else if (healthResult.exitCode !== 0) {
-      deployFailed = true;
-      return fail(
-        `Health check failed: runtime owner/socket status not available within 15s. ` +
-          `Check ~/.aria/daemon.log on ${input.target}.`,
-      );
-    }
-
-    const output: DeployOutput = {
-      success: true,
-      host,
-      port,
-      fingerprint,
-      arionName,
-      tlsType,
-    };
-
-    const statusLine = `Daemon running (port ${port ?? "unknown"})`;
-    const tlsLine = tlsType ? `TLS: ${tlsType}` : "TLS: none (HTTP only)";
-
-    return success(
-      `ARIA deployed to ${input.target}.\n` +
-        `Arion: ${arionName}\n` +
-        `Fingerprint: ${fingerprint ?? "unknown"}\n` +
-        `${tlsLine}\n` +
-        `${statusLine}`,
-      output,
-    );
-  } catch (error) {
-    deployFailed = true;
-    return fail(`Deploy failed: ${error instanceof Error ? error.message : String(error)}`);
-  } finally {
-    // A2: Rollback on failure — undo completed steps in reverse order
-    if (deployFailed && completedSteps.length > 0) {
-      const rollbackCmds = buildRollbackCommands(completedSteps);
-      for (const cmd of rollbackCmds) {
-        try {
-          await sshExec(input.target, cmd, sshOpts);
-        } catch {
-          // Best-effort rollback — don't throw during cleanup
-        }
-      }
-    }
-  }
-}