@hasna/machines 0.0.46 → 0.0.47

package/README.md

@@ -418,6 +418,32 @@ to be scoped to a short-lived approval token, or pass
 `--trusted-local-mutation` to generate a process-local
 `HASNA_MACHINES_ALLOW_MUTATIONS=1` prefix for local event recording.
 
+## Fleet hostnames (`machines hosts`)
+
+Make every fleet machine reachable by its bare name from any other machine —
+`curl http://machine001:3000` works the same on every box — without depending on
+Tailscale MagicDNS being configured. `machines hosts` writes a managed block into
+`/etc/hosts` for each machine in the manifest, choosing the best address:
+
+1. `metadata.lanAddress` from the manifest, when it is on the local machine's `/24`
+2. the peer's live direct Tailscale LAN endpoint (`CurAddr`) on the local `/24`
+3. the peer's tailnet IP (`100.64.0.0/10`) — always routable, auto-routed over the
+   LAN when co-located
+
+```bash
+machines hosts            # dry-run plan (default)
+machines hosts plan -j    # JSON plan
+machines hosts apply      # write /etc/hosts (uses sudo when the file is root-owned)
+machines hosts plan --no-warm   # skip discovering LAN endpoints (faster, tailnet IPs)
+```
+
+By default the command first runs `tailscale ping` against online peers so their
+LAN endpoints become visible and same-LAN machines resolve to their `192.168.x.x`
+address (true LAN-direct) instead of the tailnet IP. Off-LAN or offline peers fall
+back to the tailnet IP. The local machine is skipped. The managed block is delimited
+by markers, so re-running `apply` only rewrites that block and leaves the rest of
+`/etc/hosts` untouched.
+
 ## Dashboard
 
 ```bash

package/dist/agent/index.js

@@ -992,7 +992,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;

package/dist/cli/index.js

@@ -993,7 +993,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;
@@ -2714,7 +2714,7 @@ import {
   sanitizeChannelsForOutput as sanitizeChannelsForOutput2
 } from "@hasna/events";
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync13, readFileSync as readFileSync13, rmSync as rmSync3 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync14, rmSync as rmSync3 } from "fs";
 import { join as join12, resolve as resolve4 } from "path";
 
 // node_modules/chalk/source/vendor/ansi-styles/index.js
@@ -9448,6 +9448,310 @@ function renderDomainMapping(domain) {
   };
 }
 
+// src/commands/hosts.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { networkInterfaces, platform as osPlatform } from "os";
+var HOSTS_BLOCK_BEGIN = "# >>> hasna machines fleet >>>";
+var HOSTS_BLOCK_END = "# <<< hasna machines fleet <<<";
+function defaultRunner2(command) {
+  const result = spawnSync3("bash", ["-c", command], { encoding: "utf8", env: process.env });
+  return { stdout: result.stdout || "", exitCode: result.status ?? 1 };
+}
+function getHostsPath() {
+  const override = process.env["HASNA_MACHINES_HOSTS_PATH"];
+  if (override)
+    return override;
+  if (osPlatform() === "win32") {
+    return "C:\\Windows\\System32\\drivers\\etc\\hosts";
+  }
+  return "/etc/hosts";
+}
+function isIpv4(value) {
+  const parts = value.split(".");
+  if (parts.length !== 4)
+    return false;
+  return parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part))
+      return false;
+    const num = Number(part);
+    return num >= 0 && num <= 255;
+  });
+}
+function isPrivateIpv4(value) {
+  if (!isIpv4(value))
+    return false;
+  const [a, b] = value.split(".").map(Number);
+  if (a === 10)
+    return true;
+  if (a === 192 && b === 168)
+    return true;
+  if (a === 172 && b >= 16 && b <= 31)
+    return true;
+  return false;
+}
+function isTailnetIpv4(value) {
+  if (!isIpv4(value))
+    return false;
+  const [a, b] = value.split(".").map(Number);
+  return a === 100 && b >= 64 && b <= 127;
+}
+function subnet24(value) {
+  if (!isIpv4(value))
+    return null;
+  return value.split(".").slice(0, 3).join(".");
+}
+function ipFromEndpoint(endpoint) {
+  if (!endpoint)
+    return null;
+  const host = endpoint.replace(/:\d+$/, "").trim();
+  return isIpv4(host) ? host : null;
+}
+function localPrivateSubnets() {
+  const subnets = new Set;
+  const interfaces = networkInterfaces();
+  for (const addrs of Object.values(interfaces)) {
+    for (const addr of addrs ?? []) {
+      if (addr.family !== "IPv4" || addr.internal)
+        continue;
+      if (!isPrivateIpv4(addr.address))
+        continue;
+      const subnet = subnet24(addr.address);
+      if (subnet)
+        subnets.add(subnet);
+    }
+  }
+  return [...subnets];
+}
+function shortName(value) {
+  if (!value)
+    return null;
+  const trimmed = value.replace(/\.$/, "").trim();
+  if (!trimmed)
+    return null;
+  return trimmed.split(".")[0]?.toLowerCase() || null;
+}
+function machineNames(machine) {
+  const names = [];
+  for (const candidate of [machine.id, machine.hostname, shortName(machine.tailscaleName)]) {
+    const name = shortName(candidate);
+    if (name && !names.includes(name))
+      names.push(name);
+  }
+  return names;
+}
+function peerKeysForMachine(machine) {
+  return [
+    machine.id,
+    machine.hostname,
+    shortName(machine.tailscaleName),
+    machine.tailscaleName,
+    machine.sshAddress?.split("@").pop()
+  ].filter((value) => Boolean(value));
+}
+function indexPeers(tailscale) {
+  const peers = new Map;
+  if (!tailscale)
+    return peers;
+  const add = (peer) => {
+    if (!peer)
+      return;
+    const id = shortName(peer.HostName) || shortName(peer.DNSName);
+    if (id)
+      peers.set(id, peer);
+  };
+  add(tailscale.Self);
+  for (const peer of Object.values(tailscale.Peer ?? {}))
+    add(peer);
+  return peers;
+}
+function findPeer(machine, peers) {
+  for (const key of peerKeysForMachine(machine)) {
+    const peer = peers.get(shortName(key) || key);
+    if (peer)
+      return peer;
+  }
+  return null;
+}
+function tailnetIp(peer) {
+  if (!peer)
+    return null;
+  for (const ip of peer.TailscaleIPs ?? []) {
+    if (isTailnetIpv4(ip))
+      return ip;
+  }
+  return null;
+}
+function metadataString2(metadata, key) {
+  if (!metadata)
+    return null;
+  const value = metadata[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function buildFleetHostEntries(input) {
+  const { manifest, tailscale, localSubnets, localMachineId } = input;
+  const peers = indexPeers(tailscale);
+  const subnetSet = new Set(localSubnets);
+  const entries = [];
+  const unresolved = [];
+  const warnings = [];
+  for (const machine of manifest.machines) {
+    if (localMachineId && machine.id === localMachineId)
+      continue;
+    const names = machineNames(machine);
+    if (names.length === 0)
+      continue;
+    const peer = findPeer(machine, peers);
+    const lanAddress = metadataString2(machine.metadata, "lanAddress");
+    const explicitIp = metadataString2(machine.metadata, "ipAddress");
+    const curLanIp = ipFromEndpoint(peer?.CurAddr);
+    const tnet = tailnetIp(peer);
+    let ip = null;
+    let source = null;
+    if (lanAddress && isPrivateIpv4(lanAddress) && subnetSet.has(subnet24(lanAddress) ?? "")) {
+      ip = lanAddress;
+      source = "manifest_lan";
+    } else if (curLanIp && isPrivateIpv4(curLanIp) && subnetSet.has(subnet24(curLanIp) ?? "")) {
+      ip = curLanIp;
+      source = "tailscale_lan";
+    } else if (tnet) {
+      ip = tnet;
+      source = "tailscale";
+    } else if (explicitIp && isIpv4(explicitIp)) {
+      ip = explicitIp;
+      source = "manifest_ip";
+    }
+    if (!ip || !source) {
+      unresolved.push(machine.id);
+      continue;
+    }
+    entries.push({ id: machine.id, ip, names, source });
+  }
+  entries.sort((left, right) => left.id.localeCompare(right.id));
+  return { entries, unresolved, warnings };
+}
+function renderHostsBlock(entries) {
+  const lines = [
+    HOSTS_BLOCK_BEGIN,
+    "# Managed by `machines hosts apply`. Do not edit between these markers.",
+    ...entries.map((entry) => `${entry.ip}	${entry.names.join(" ")}`),
+    HOSTS_BLOCK_END
+  ];
+  return lines.join(`
+`);
+}
+function mergeHostsContent(existing, block) {
+  const beginIndex = existing.indexOf(HOSTS_BLOCK_BEGIN);
+  const endIndex = existing.indexOf(HOSTS_BLOCK_END);
+  if (beginIndex !== -1 && endIndex !== -1 && endIndex > beginIndex) {
+    const before = existing.slice(0, beginIndex).replace(/\n+$/, "");
+    const after = existing.slice(endIndex + HOSTS_BLOCK_END.length).replace(/^\n+/, "");
+    const head = before ? `${before}
+` : "";
+    const tail = after ? `
+${after}` : `
+`;
+    return `${head}${block}${tail}`;
+  }
+  const base = existing.replace(/\n+$/, "");
+  const prefix = base ? `${base}
+
+` : "";
+  return `${prefix}${block}
+`;
+}
+function loadTailscale(runner, warnings) {
+  if (runner("command -v tailscale >/dev/null 2>&1").exitCode !== 0) {
+    warnings.push("tailscale_not_available");
+    return null;
+  }
+  const result = runner("tailscale status --json");
+  if (result.exitCode !== 0) {
+    warnings.push("tailscale_status_failed");
+    return null;
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    warnings.push("tailscale_status_invalid_json");
+    return null;
+  }
+}
+function collectPingTargets(tailscale, localSubnets) {
+  if (!tailscale)
+    return [];
+  const subnetSet = new Set(localSubnets);
+  const targets = [];
+  for (const peer of Object.values(tailscale.Peer ?? {})) {
+    if (!peer.Online)
+      continue;
+    const cur = ipFromEndpoint(peer.CurAddr);
+    if (cur && isPrivateIpv4(cur) && subnetSet.has(subnet24(cur) ?? ""))
+      continue;
+    const tnet = tailnetIp(peer);
+    if (tnet && !targets.includes(tnet))
+      targets.push(tnet);
+  }
+  return targets;
+}
+function warmDirectPaths(runner, targets, timeoutSeconds = 2) {
+  for (const target of targets) {
+    runner(`tailscale ping --c 1 --timeout ${timeoutSeconds}s ${target} >/dev/null 2>&1 || true`);
+  }
+}
+function resolveLocalMachineId(tailscale, explicit) {
+  if (explicit)
+    return explicit;
+  return shortName(tailscale?.Self?.HostName) || shortName(process.env["HOSTNAME"]) || null;
+}
+function planFleetHosts(options = {}) {
+  const runner = options.runner ?? defaultRunner2;
+  const warnings = [];
+  let tailscale = loadTailscale(runner, warnings);
+  const manifest = readManifest();
+  const localSubnets = options.localSubnets ?? localPrivateSubnets();
+  if (options.warm !== false && tailscale && localSubnets.length > 0) {
+    const targets = collectPingTargets(tailscale, localSubnets);
+    if (targets.length > 0) {
+      warmDirectPaths(runner, targets, options.warmTimeoutSeconds);
+      tailscale = loadTailscale(runner, warnings) ?? tailscale;
+    }
+  }
+  const localMachineId = resolveLocalMachineId(tailscale, options.localMachineId);
+  const built = buildFleetHostEntries({ manifest, tailscale, localSubnets, localMachineId });
+  const block = renderHostsBlock(built.entries);
+  return {
+    hostsPath: getHostsPath(),
+    entries: built.entries,
+    unresolved: built.unresolved,
+    warnings: [...warnings, ...built.warnings],
+    block,
+    localSubnets
+  };
+}
+function applyFleetHosts(options = {}) {
+  const plan = planFleetHosts(options);
+  const hostsPath = plan.hostsPath;
+  const existing = existsSync7(hostsPath) ? readFileSync5(hostsPath, "utf8") : "";
+  const merged = mergeHostsContent(existing, plan.block);
+  let viaSudo = false;
+  try {
+    writeFileSync3(hostsPath, merged, "utf8");
+  } catch (error) {
+    const code = error?.code;
+    if (code !== "EACCES" && code !== "EPERM")
+      throw error;
+    const runner = options.runner ?? defaultRunner2;
+    const encoded = Buffer.from(merged, "utf8").toString("base64");
+    const result = runner(`printf %s '${encoded}' | base64 -d | sudo tee ${hostsPath} >/dev/null`);
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to write ${hostsPath} (need sudo). Re-run with elevated privileges.`);
+    }
+    viaSudo = true;
+  }
+  return { ...plan, written: true, viaSudo };
+}
+
 // src/commands/diff.ts
 function packageNames(machine) {
   return (machine.packages || []).map((pkg) => pkg.name).sort();
@@ -9801,7 +10105,7 @@ function runTailscaleInstallPlan(plan, options = {}, runner = runMachineCommand)
 }
 
 // src/commands/notifications.ts
-import { accessSync, constants, existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { accessSync, constants, existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
 import { delimiter, isAbsolute, join as join7 } from "path";
 init_paths();
 var notificationChannelSchema = exports_external.object({
@@ -9986,10 +10290,10 @@ function getDefaultNotificationConfig() {
   };
 }
 function readNotificationConfig(path = getNotificationsPath()) {
-  if (!existsSync7(path)) {
+  if (!existsSync8(path)) {
     return getDefaultNotificationConfig();
   }
-  return notificationConfigSchema.parse(JSON.parse(readFileSync5(path, "utf8")));
+  return notificationConfigSchema.parse(JSON.parse(readFileSync6(path, "utf8")));
 }
 function writeNotificationConfig(config, path = getNotificationsPath()) {
   ensureParentDir(path);
@@ -9998,7 +10302,7 @@ function writeNotificationConfig(config, path = getNotificationsPath()) {
     updatedAt: new Date().toISOString(),
     channels: sortChannels(config.channels)
   };
-  writeFileSync3(path, `${JSON.stringify(nextConfig, null, 2)}
+  writeFileSync4(path, `${JSON.stringify(nextConfig, null, 2)}
 `, "utf8");
   return nextConfig;
 }
@@ -10087,7 +10391,7 @@ async function testNotificationChannel(channelId, event = "manual.test", message
 
 // src/commands/ports.ts
 init_db();
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync4 } from "child_process";
 function parseSsOutput(output) {
   return output.trim().split(`
 `).map((line) => line.trim()).filter(Boolean).map((line) => {
@@ -10129,7 +10433,7 @@ function listPorts(machineId) {
   const isLocal = targetMachineId === getLocalMachineId();
   const localCommand = "if command -v ss >/dev/null 2>&1; then ss -ltnpH; else lsof -nP -iTCP -sTCP:LISTEN; fi";
   const command = isLocal ? localCommand : buildSshCommand(targetMachineId, localCommand);
-  const result = spawnSync3("bash", ["-lc", command], { encoding: "utf8" });
+  const result = spawnSync4("bash", ["-lc", command], { encoding: "utf8" });
   if (result.status !== 0) {
     throw new Error(result.stderr || `Failed to list ports for ${targetMachineId}`);
   }
@@ -10141,7 +10445,7 @@ function listPorts(machineId) {
 }
 
 // src/commands/runtime.ts
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync5 } from "child_process";
 import { setTimeout as sleep } from "timers/promises";
 import { EventsClient } from "@hasna/events";
 function shellQuote5(value) {
@@ -10186,7 +10490,7 @@ function buildTmuxPaneDiedHookPlan(options = {}) {
 }
 function probeTmuxPane(target, tmuxCommand = process.env["HASNA_MACHINES_TMUX_BIN"] || "tmux") {
   const checkedAt = new Date().toISOString();
-  const result = spawnSync4(tmuxCommand, ["display-message", "-p", "-t", target, "#{pane_id}"], {
+  const result = spawnSync5(tmuxCommand, ["display-message", "-p", "-t", target, "#{pane_id}"], {
     encoding: "utf8",
     timeout: 5000
   });
@@ -10278,7 +10582,7 @@ function shellQuote6(value) {
 function shellCommand2(command) {
   return command.map(shellQuote6).join(" ");
 }
-function metadataString2(metadata, keys) {
+function metadataString3(metadata, keys) {
   if (!metadata)
     return null;
   for (const key of keys) {
@@ -10328,8 +10632,8 @@ function resolveScreenCredentials(machineId, options = {}) {
   const screen = resolveScreenTarget(machineId, { ...options, topology });
   const entry = topology.machines.find((machine) => machine.machine_id === screen.machineId);
   const metadata = entry?.metadata;
-  const metadataUser = metadataString2(metadata, ["screenUser", "screen_user", "user", "username"]);
-  const metadataPasswordSecret = metadataString2(metadata, [
+  const metadataUser = metadataString3(metadata, ["screenUser", "screen_user", "user", "username"]);
+  const metadataPasswordSecret = metadataString3(metadata, [
     "screenPasswordSecret",
     "screen_password_secret",
     "screenVncPasswordSecret",
@@ -10386,7 +10690,7 @@ function buildScreenEnableCommand(machineId, options = {}) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync8, lstatSync, readFileSync as readFileSync6, symlinkSync, copyFileSync } from "fs";
+import { existsSync as existsSync9, lstatSync, readFileSync as readFileSync7, symlinkSync, copyFileSync } from "fs";
 import { homedir as homedir5 } from "os";
 init_paths();
 init_db();
@@ -10441,15 +10745,15 @@ function detectFileActions(machine) {
     throw new Error(`Remote file sync planning is not supported for ${machine.id}; refusing to inspect or apply local paths as remote state.`);
   }
   return (machine.files || []).map((file, index) => {
-    const sourceExists = existsSync8(file.source);
-    const targetExists = existsSync8(file.target);
+    const sourceExists = existsSync9(file.source);
+    const targetExists = existsSync9(file.target);
     let status = "missing";
     if (sourceExists && targetExists) {
       if (file.mode === "symlink") {
         status = lstatSync(file.target).isSymbolicLink() ? "ok" : "drifted";
       } else {
-        const source = readFileSync6(file.source, "utf8");
-        const target = readFileSync6(file.target, "utf8");
+        const source = readFileSync7(file.source, "utf8");
+        const target = readFileSync7(file.target, "utf8");
         status = source === target ? "ok" : "drifted";
       }
     }
@@ -10802,7 +11106,7 @@ function parseKeyValue(stdout) {
   }
   return result;
 }
-function defaultRunner2(machineId, command) {
+function defaultRunner3(machineId, command) {
   return runMachineCommand(machineId, command);
 }
 function inspectCommand(machineId, spec, runner) {
@@ -10956,7 +11260,7 @@ function workspaceCheck(machineId, spec, runner) {
 }
 function checkMachineCompatibility(options = {}) {
   const machineId = options.machineId ?? getLocalMachineId();
-  const runner = options.runner ?? defaultRunner2;
+  const runner = options.runner ?? defaultRunner3;
   const commands = options.commands ?? DEFAULT_COMMANDS;
   const packages = options.packages ?? defaultPackages();
   const workspaces = options.workspaces ?? [];
@@ -11176,9 +11480,9 @@ function runDoctor(machineId, options = {}) {
 
 // src/commands/daemon.ts
 import { execFileSync } from "child_process";
-import { chmodSync, existsSync as existsSync9, readFileSync as readFileSync7, statSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
+import { chmodSync, existsSync as existsSync10, readFileSync as readFileSync8, statSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync5 } from "fs";
 import { delimiter as delimiter2, dirname as dirname4 } from "path";
-import { platform as osPlatform } from "os";
+import { platform as osPlatform2 } from "os";
 var DEFAULT_SERVICE_NAME = "machines-agent";
 var DEFAULT_EXECUTABLE = "/usr/local/bin/machines-agent";
 var DEFAULT_INTERVAL_MS = 30000;
@@ -11235,7 +11539,7 @@ function runDaemonServicePlan(plan, options = {}) {
         };
       }
       mkdirSync2(dirname4(path), { recursive: true });
-      writeFileSync4(path, content, "utf8");
+      writeFileSync5(path, content, "utf8");
       chmodSync(path, Number.parseInt(file.mode, 8));
       filesWritten.push(path);
     }
@@ -11330,7 +11634,7 @@ function normalizeServiceName(value, warnings) {
   return DEFAULT_SERVICE_NAME;
 }
 function normalizePlatform3(value, warnings) {
-  const raw = value ?? osPlatform();
+  const raw = value ?? osPlatform2();
   if (raw === "darwin" || raw === "macos")
     return "macos";
   if (raw === "linux")
@@ -11591,7 +11895,7 @@ function bunRuntimeCandidates(executable) {
 }
 function isBunShebangScript(executable) {
   try {
-    const content = readFileSync7(executable, "utf8").slice(0, 256);
+    const content = readFileSync8(executable, "utf8").slice(0, 256);
     const firstLine2 = content.split(/\r?\n/, 1)[0] ?? "";
     return /^#!.*\bbun\b/.test(firstLine2);
   } catch {
@@ -11599,7 +11903,7 @@ function isBunShebangScript(executable) {
   }
 }
 function isExecutableFile(path) {
-  if (!existsSync9(path))
+  if (!existsSync10(path))
     return false;
   try {
     const stats = statSync(path);
@@ -12222,7 +12526,7 @@ function runSelfTest() {
 // src/commands/clipboard.ts
 init_paths();
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync10, readFileSync as readFileSync8, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync9, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
 import { join as join8 } from "path";
 var DEFAULT_CONFIG = {
   version: 1,
@@ -12253,25 +12557,25 @@ function getDefaultConfig() {
 }
 function readConfig(configPath) {
   const path = resolveConfigPath(configPath);
-  if (!existsSync10(path)) {
+  if (!existsSync11(path)) {
     return getDefaultConfig();
   }
-  const parsed = JSON.parse(readFileSync8(path, "utf8"));
+  const parsed = JSON.parse(readFileSync9(path, "utf8"));
   return { ...getDefaultConfig(), ...parsed };
 }
 function writeConfig(config, configPath) {
   const path = resolveConfigPath(configPath);
   ensureParentDir(path);
-  writeFileSync5(path, `${JSON.stringify(config, null, 2)}
+  writeFileSync6(path, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 function readHistory(historyPath) {
   const path = resolveHistoryPath(historyPath);
-  if (!existsSync10(path)) {
+  if (!existsSync11(path)) {
     return [];
   }
   try {
-    return JSON.parse(readFileSync8(path, "utf8"));
+    return JSON.parse(readFileSync9(path, "utf8"));
   } catch {
     return [];
   }
@@ -12279,7 +12583,7 @@ function readHistory(historyPath) {
 function writeHistory(entries, historyPath) {
   const path = resolveHistoryPath(historyPath);
   ensureParentDir(path);
-  writeFileSync5(path, `${JSON.stringify(entries, null, 2)}
+  writeFileSync6(path, `${JSON.stringify(entries, null, 2)}
 `, "utf8");
 }
 function computeHash(content) {
@@ -12300,12 +12604,12 @@ function sanitizeClipboardForRead(content, maxSizeBytes, skipPatterns) {
 }
 function getOrCreateClipboardKey() {
   const keyPath = getClipboardKeyPath();
-  if (existsSync10(keyPath)) {
-    return readFileSync8(keyPath, "utf8").trim();
+  if (existsSync11(keyPath)) {
+    return readFileSync9(keyPath, "utf8").trim();
   }
   const key = createHash2("sha256").update(crypto.randomUUID()).digest("hex").slice(0, 32);
   ensureParentDir(keyPath);
-  writeFileSync5(keyPath, `${key}
+  writeFileSync6(keyPath, `${key}
 `, "utf8");
   return key;
 }
@@ -12340,7 +12644,7 @@ function addClipboardEntry(entry, historyPath) {
 }
 function clearClipboardHistory(historyPath) {
   const path = resolveHistoryPath(historyPath);
-  if (existsSync10(path)) {
+  if (existsSync11(path)) {
     rmSync2(path);
   }
 }
@@ -12356,7 +12660,7 @@ function getClipboardStatus(historyPath) {
 
 // src/commands/clipboard-daemon.ts
 init_paths();
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
 import { join as join9 } from "path";
 import { createHash as createHash4 } from "crypto";
 
@@ -12364,7 +12668,7 @@ import { createHash as createHash4 } from "crypto";
 init_paths();
 import { createServer } from "http";
 import { createHash as createHash3 } from "crypto";
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 function readLocalClipboardSync() {
   const platform5 = process.platform;
   if (platform5 === "darwin") {
@@ -12410,7 +12714,7 @@ function hasCommand3(binary) {
 function loadSharedSecret() {
   const keyPath = getClipboardKeyPath();
   try {
-    return readFileSync9(keyPath, "utf8").trim();
+    return readFileSync10(keyPath, "utf8").trim();
   } catch {
     return "";
   }
@@ -12577,18 +12881,18 @@ function computeHash2(content) {
 }
 function loadSharedSecret2() {
   try {
-    return readFileSync10(getClipboardKeyPath(), "utf8").trim();
+    return readFileSync11(getClipboardKeyPath(), "utf8").trim();
   } catch {
     return "";
   }
 }
 function writePid(pid) {
-  writeFileSync6(DAEMON_PID_PATH, `${pid}
+  writeFileSync7(DAEMON_PID_PATH, `${pid}
 `);
 }
 function readPid() {
   try {
-    const pid = Number.parseInt(readFileSync10(DAEMON_PID_PATH, "utf8").trim());
+    const pid = Number.parseInt(readFileSync11(DAEMON_PID_PATH, "utf8").trim());
     return Number.isFinite(pid) ? pid : null;
   } catch {
     return null;
@@ -12689,7 +12993,7 @@ async function discoverPeers() {
 
 // src/commands/heal.ts
 init_paths();
-import { existsSync as existsSync11, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "fs";
 import { join as join10 } from "path";
 var DEFAULT_THRESHOLDS = {
   reconnect: 3,
@@ -12741,9 +13045,9 @@ function getHealStatePath() {
 }
 function readHealConfig(path) {
   const p = path || getHealConfigPath();
-  if (!existsSync11(p))
+  if (!existsSync12(p))
     return { ...DEFAULT_HEAL_CONFIG, thresholds: { ...DEFAULT_THRESHOLDS } };
-  const parsed = JSON.parse(readFileSync11(p, "utf8"));
+  const parsed = JSON.parse(readFileSync12(p, "utf8"));
   return {
     ...DEFAULT_HEAL_CONFIG,
     ...parsed,
@@ -12754,15 +13058,15 @@ function readHealConfig(path) {
 function writeHealConfig(config, path) {
   const p = path || getHealConfigPath();
   ensureParentDir(p);
-  writeFileSync7(p, `${JSON.stringify(config, null, 2)}
+  writeFileSync8(p, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 function readHealState(path) {
   const p = path || getHealStatePath();
-  if (!existsSync11(p))
+  if (!existsSync12(p))
     return defaultHealState();
   try {
-    return { ...defaultHealState(), ...JSON.parse(readFileSync11(p, "utf8")) };
+    return { ...defaultHealState(), ...JSON.parse(readFileSync12(p, "utf8")) };
   } catch {
     return defaultHealState();
   }
@@ -12770,7 +13074,7 @@ function readHealState(path) {
 function writeHealState(state, path) {
   const p = path || getHealStatePath();
   ensureParentDir(p);
-  writeFileSync7(p, `${JSON.stringify(state, null, 2)}
+  writeFileSync8(p, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
 function evaluateHealth(probe, config, state) {
@@ -12889,7 +13193,7 @@ function sh(cmd, timeoutMs = 8000) {
 }
 function getCurrentBootId() {
   try {
-    return readFileSync11("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    return readFileSync12("/proc/sys/kernel/random/boot_id", "utf8").trim();
   } catch {
     return "";
   }
@@ -12975,7 +13279,7 @@ function executeAction(action, config) {
 
 // src/commands/heal-daemon.ts
 init_paths();
-import { existsSync as existsSync12, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
 import { join as join11 } from "path";
 var DAEMON_PID_PATH2 = join11(getDataDir(), "heal-daemon.pid");
 var SERVICE_PATH = "/etc/systemd/system/machines-heal.service";
@@ -13018,12 +13322,12 @@ function runHealOnce(config, opts = {}) {
   return result;
 }
 function writePid2(pid) {
-  writeFileSync8(DAEMON_PID_PATH2, `${pid}
+  writeFileSync9(DAEMON_PID_PATH2, `${pid}
 `);
 }
 function readPid2() {
   try {
-    const pid = Number.parseInt(readFileSync12(DAEMON_PID_PATH2, "utf8").trim());
+    const pid = Number.parseInt(readFileSync13(DAEMON_PID_PATH2, "utf8").trim());
     return Number.isFinite(pid) ? pid : null;
   } catch {
     return null;
@@ -13095,9 +13399,9 @@ function applyDeterminism(config) {
 }
 function enableHardwareWatchdog() {
   const log2 = [];
-  if (!existsSync12(SYSTEM_CONF))
+  if (!existsSync13(SYSTEM_CONF))
     return ["/etc/systemd/system.conf not found; skipping hardware watchdog"];
-  let conf = readFileSync12(SYSTEM_CONF, "utf8");
+  let conf = readFileSync13(SYSTEM_CONF, "utf8");
   const set = (key, value) => {
     const re = new RegExp(`^#?\\s*${key}=.*$`, "m");
     if (re.test(conf))
@@ -13109,7 +13413,7 @@ ${key}=${value}
   };
   set("RuntimeWatchdogSec", "20s");
   set("RebootWatchdogSec", "2min");
-  writeFileSync8(SYSTEM_CONF, conf);
+  writeFileSync9(SYSTEM_CONF, conf);
   sh2("systemctl daemon-reexec");
   log2.push("hardware watchdog: RuntimeWatchdogSec=20s RebootWatchdogSec=2min");
   return log2;
@@ -13127,7 +13431,7 @@ function binPath() {
     candidates.push(`${home}/.bun/bin/machines`);
   candidates.push("/root/.bun/bin/machines", "/usr/local/bin/machines");
   for (const c of candidates) {
-    if (c && existsSync12(c))
+    if (c && existsSync13(c))
       return c;
   }
   return "machines";
@@ -13154,7 +13458,7 @@ Environment=PATH=${binDir}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sb
 [Install]
 WantedBy=multi-user.target
 `;
-  writeFileSync8(SERVICE_PATH, unit);
+  writeFileSync9(SERVICE_PATH, unit);
   sh2("systemctl daemon-reload");
   sh2("systemctl enable --now machines-heal.service");
   log2.push(`installed + enabled ${SERVICE_PATH} (ExecStart=${exec} heal daemon)`);
@@ -13163,7 +13467,7 @@ WantedBy=multi-user.target
 function uninstallHealService() {
   const log2 = [];
   sh2("systemctl disable --now machines-heal.service 2>/dev/null || true");
-  if (existsSync12(SERVICE_PATH)) {
+  if (existsSync13(SERVICE_PATH)) {
     sh2(`rm -f ${SERVICE_PATH}`);
     sh2("systemctl daemon-reload");
     log2.push(`removed ${SERVICE_PATH}`);
@@ -13174,7 +13478,7 @@ function uninstallHealService() {
 }
 function healServiceStatus() {
   return {
-    installed: existsSync12(SERVICE_PATH),
+    installed: existsSync13(SERVICE_PATH),
     active: sh2("systemctl is-active machines-heal.service").out === "active",
     enabled: sh2("systemctl is-enabled machines-heal.service 2>/dev/null").out === "enabled"
   };
@@ -13538,9 +13842,9 @@ function withEventStoreScope2(args) {
   return { event_store_dir: eventStoreDir2(), ...args };
 }
 function readJsonArrayFile(path) {
-  if (!existsSync13(path))
+  if (!existsSync14(path))
     return [];
-  const raw = readFileSync13(path, "utf8").trim();
+  const raw = readFileSync14(path, "utf8").trim();
   if (!raw)
     return [];
   const parsed = JSON.parse(raw);
@@ -13831,7 +14135,7 @@ manifestCommand.command("add").description("Add or replace a machine in the flee
       console.error("error: --from-stdin requires piped input");
       process.exit(1);
     }
-    const input = readFileSync13(0, "utf8");
+    const input = readFileSync14(0, "utf8");
     const machine2 = JSON.parse(input);
     requireCliMutation("manifest_add", typeof options["approvalToken"] === "string" ? options["approvalToken"] : undefined, { machineId: machine2.id, args: machine2 });
     console.log(JSON.stringify(manifestAdd(machine2), null, 2));
@@ -14058,6 +14362,37 @@ dnsCommand.command("list").description("List saved local domain mappings").optio
 dnsCommand.command("render").description("Render hosts/proxy configuration for a domain").argument("<domain>", "Domain name").option("-j, --json", "Print JSON output", false).action((domain) => {
   console.log(JSON.stringify(renderDomainMapping(domain), null, 2));
 });
+var hostsCommand = program2.command("hosts").description("Sync fleet machine names into /etc/hosts so machine<NN>:port resolves on the LAN and tailnet");
+function printHostsResult(plan, applied, viaSudo = false) {
+  console.log(`hosts file: ${plan.hostsPath}`);
+  console.log(`local subnets: ${plan.localSubnets.join(", ") || "none"}`);
+  for (const entry of plan.entries) {
+    console.log(`  ${entry.ip}	${entry.names.join(" ")}	(${entry.source})`);
+  }
+  if (plan.unresolved.length > 0) {
+    console.log(`unresolved: ${plan.unresolved.join(", ")}`);
+  }
+  if (plan.warnings.length > 0) {
+    console.log(`warnings: ${plan.warnings.join(", ")}`);
+  }
+  console.log(applied ? `applied ${plan.entries.length} entries${viaSudo ? " (via sudo)" : ""}` : "dry run \u2014 re-run `machines hosts apply` to write");
+}
+hostsCommand.command("plan", { isDefault: true }).description("Preview the managed /etc/hosts block for the fleet (dry run)").option("-j, --json", "Print JSON output", false).option("--no-warm", "Skip establishing direct Tailscale paths to discover LAN endpoints").action((options) => {
+  const plan = planFleetHosts({ warm: options.warm });
+  if (options.json) {
+    console.log(JSON.stringify(plan, null, 2));
+    return;
+  }
+  printHostsResult(plan, false);
+});
+hostsCommand.command("apply").description("Write the managed fleet block into /etc/hosts (uses sudo when required)").option("-j, --json", "Print JSON output", false).option("--no-warm", "Skip establishing direct Tailscale paths to discover LAN endpoints").action((options) => {
+  const result = applyFleetHosts({ warm: options.warm });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  printHostsResult(result, true, result.viaSudo);
+});
 notificationsCommand.command("add").description("Add or replace a notification channel").requiredOption("--id <id>", "Channel identifier").requiredOption("--type <type>", "email | webhook | command").requiredOption("--target <target>", "Email, webhook URL, or command executable").option("--arg <arg...>", "Command argument for command transports", collectOptionValues, []).option("--event <event...>", "Events routed to this channel", ["setup_failed", "sync_failed"]).option("--disabled", "Create the channel in disabled state", false).option("--approval-token <token>", "Operator mutation approval token for command transports").option("-j, --json", "Print JSON output", false).action((options) => {
   const enabled = !options.disabled;
   const events = [...new Set(options.event)];

package/dist/commands/hosts.d.ts

@@ -0,0 +1,81 @@
+import type { FleetManifest } from "../types.js";
+export declare const HOSTS_BLOCK_BEGIN = "# >>> hasna machines fleet >>>";
+export declare const HOSTS_BLOCK_END = "# <<< hasna machines fleet <<<";
+/**
+ * Where each fleet host entry's IP came from, in descending preference:
+ *  - manifest_lan   : a `metadata.lanAddress` on the same /24 as this machine
+ *  - tailscale_lan  : the peer's live direct LAN endpoint (CurAddr) on this /24
+ *  - tailscale      : the peer's tailnet (100.64.0.0/10) IP — always routable
+ *  - manifest_ip    : an explicit `metadata.ipAddress` override
+ */
+export type HostEntrySource = "manifest_lan" | "tailscale_lan" | "tailscale" | "manifest_ip";
+export interface FleetHostEntry {
+    id: string;
+    ip: string;
+    names: string[];
+    source: HostEntrySource;
+}
+export interface RawTailscalePeer {
+    HostName?: string;
+    DNSName?: string;
+    TailscaleIPs?: string[];
+    CurAddr?: string;
+    Online?: boolean;
+}
+export interface RawTailscaleStatus {
+    Self?: RawTailscalePeer;
+    Peer?: Record<string, RawTailscalePeer>;
+}
+export interface HostsCommandResult {
+    stdout: string;
+    exitCode: number;
+}
+export type HostsCommandRunner = (command: string) => HostsCommandResult;
+export interface BuildFleetHostEntriesInput {
+    manifest: FleetManifest;
+    tailscale: RawTailscaleStatus | null;
+    localSubnets: string[];
+    localMachineId?: string | null;
+}
+export interface BuildFleetHostEntriesResult {
+    entries: FleetHostEntry[];
+    unresolved: string[];
+    warnings: string[];
+}
+export interface FleetHostsPlan extends BuildFleetHostEntriesResult {
+    hostsPath: string;
+    block: string;
+    localSubnets: string[];
+}
+export interface FleetHostsOptions {
+    runner?: HostsCommandRunner;
+    localSubnets?: string[];
+    localMachineId?: string | null;
+    /**
+     * Establish direct Tailscale paths to online peers first so their LAN
+     * endpoints (CurAddr) become visible and can be preferred over tailnet IPs.
+     * Defaults to true.
+     */
+    warm?: boolean;
+    warmTimeoutSeconds?: number;
+}
+export interface ApplyFleetHostsResult extends FleetHostsPlan {
+    written: boolean;
+    viaSudo: boolean;
+}
+export declare function getHostsPath(): string;
+export declare function isPrivateIpv4(value: string): boolean;
+export declare function subnet24(value: string): string | null;
+export declare function localPrivateSubnets(): string[];
+export declare function buildFleetHostEntries(input: BuildFleetHostEntriesInput): BuildFleetHostEntriesResult;
+export declare function renderHostsBlock(entries: FleetHostEntry[]): string;
+export declare function mergeHostsContent(existing: string, block: string): string;
+/**
+ * Online peers that do not yet expose a same-subnet LAN endpoint but do have a
+ * tailnet IP — pinging these establishes a direct path so their LAN address
+ * becomes resolvable.
+ */
+export declare function collectPingTargets(tailscale: RawTailscaleStatus | null, localSubnets: string[]): string[];
+export declare function warmDirectPaths(runner: HostsCommandRunner, targets: string[], timeoutSeconds?: number): void;
+export declare function planFleetHosts(options?: FleetHostsOptions): FleetHostsPlan;
+export declare function applyFleetHosts(options?: FleetHostsOptions): ApplyFleetHostsResult;

package/dist/index.js

@@ -19926,7 +19926,7 @@ class JSONSchemaGenerator {
               if (val === undefined) {
                 if (this.unrepresentable === "throw") {
                   throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-                }
+                } else {}
               } else if (typeof val === "bigint") {
                 if (this.unrepresentable === "throw") {
                   throw new Error("BigInt literals cannot be represented in JSON Schema");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/machines",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "Machine fleet management CLI + MCP for developers",
   "type": "module",
   "license": "Apache-2.0",