@hasna/machines 0.0.15 → 0.0.17

package/dist/mcp/index.js

@@ -4218,6 +4218,7 @@ function detectCurrentMachineManifest() {
 
 // src/remote.ts
 import { spawnSync as spawnSync2 } from "child_process";
+import { hostname as hostname4 } from "os";
 
 // src/db.ts
 import { Database } from "bun:sqlite";
@@ -4318,62 +4319,397 @@ function recordSyncRun(machineId, status, actions) {
      VALUES (?, ?, ?, ?, ?, ?)`).run(crypto.randomUUID(), machineId, status, JSON.stringify(actions), now, now);
 }
 
-// src/commands/ssh.ts
+// src/topology.ts
+import { existsSync as existsSync4 } from "fs";
+import { arch as arch2, hostname as hostname3, platform as platform2, userInfo as userInfo2 } from "os";
 import { spawnSync } from "child_process";
+var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
+var MACHINES_PACKAGE_NAME = "@hasna/machines";
+function normalizePlatform2(value = platform2()) {
+  const normalized = value.toLowerCase();
+  if (normalized === "darwin" || normalized === "macos")
+    return "macos";
+  if (normalized === "win32" || normalized === "windows")
+    return "windows";
+  if (normalized === "linux")
+    return "linux";
+  return value;
+}
+function defaultRunner(command) {
+  const result = spawnSync("bash", ["-c", command], {
+    encoding: "utf8",
+    env: process.env
+  });
+  return {
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    exitCode: result.status ?? 1
+  };
+}
+function hasCommand(command, runner) {
+  return runner(`command -v ${command} >/dev/null 2>&1`).exitCode === 0;
+}
+function parseTailscaleStatus(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object")
+      return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function loadTailscalePeers(runner, warnings) {
+  const peers = new Map;
+  if (!hasCommand("tailscale", runner)) {
+    warnings.push("tailscale_not_available");
+    return peers;
+  }
+  const result = runner("tailscale status --json");
+  if (result.exitCode !== 0) {
+    warnings.push(`tailscale_status_failed:${result.stderr.trim() || result.exitCode}`);
+    return peers;
+  }
+  const status = parseTailscaleStatus(result.stdout);
+  if (!status) {
+    warnings.push("tailscale_status_invalid_json");
+    return peers;
+  }
+  const addPeer = (peer) => {
+    if (!peer)
+      return;
+    const id = peer.HostName || peer.DNSName?.split(".")[0];
+    if (id)
+      peers.set(id, peer);
+  };
+  addPeer(status.Self);
+  for (const peer of Object.values(status.Peer ?? {}))
+    addPeer(peer);
+  return peers;
+}
+function machineKeys(machine) {
+  return [
+    machine.id,
+    machine.hostname,
+    machine.tailscaleName?.split(".")[0],
+    machine.tailscaleName,
+    machine.sshAddress?.split("@").pop()
+  ].filter((value) => Boolean(value));
+}
+function findTailscalePeer(machine, machineId, peers) {
+  if (machine) {
+    for (const key of machineKeys(machine)) {
+      const peer = peers.get(key) ?? peers.get(key.replace(/\.$/, ""));
+      if (peer)
+        return peer;
+    }
+  }
+  return peers.get(machineId) ?? null;
+}
 function envReachableHosts() {
   const raw = process.env["HASNA_MACHINES_REACHABLE_HOSTS"];
   return new Set((raw || "").split(",").map((value) => value.trim()).filter(Boolean));
 }
-function isReachable(host) {
+function manifestHostReachable(target) {
   const overrides = envReachableHosts();
-  if (overrides.size > 0) {
-    return overrides.has(host);
+  if (overrides.size === 0)
+    return null;
+  return overrides.has(target);
+}
+function routeHints(input) {
+  const hints = [];
+  if (input.machineId === input.localMachineId) {
+    hints.push({ kind: "local", target: "localhost", reachable: true });
+  }
+  if (input.manifest?.sshAddress) {
+    hints.push({ kind: "ssh", target: input.manifest.sshAddress, reachable: manifestHostReachable(input.manifest.sshAddress) });
+  }
+  if (input.manifest?.hostname) {
+    hints.push({ kind: "lan", target: input.manifest.hostname, reachable: manifestHostReachable(input.manifest.hostname) });
   }
-  const probe = spawnSync("bash", ["-lc", `getent hosts ${host} >/dev/null 2>&1 || ping -c 1 -W 1 ${host} >/dev/null 2>&1`], {
-    stdio: "ignore"
+  const tailscaleTarget = input.manifest?.tailscaleName ?? input.peer?.DNSName ?? input.peer?.TailscaleIPs?.[0];
+  if (tailscaleTarget) {
+    hints.push({ kind: "tailscale", target: tailscaleTarget.replace(/\.$/, ""), reachable: input.peer?.Online ?? null });
+  }
+  return hints;
+}
+function routeRank(hint) {
+  if (hint.kind === "local")
+    return 0;
+  if (hint.reachable === true && hint.kind === "ssh")
+    return 1;
+  if (hint.reachable === true && hint.kind === "lan")
+    return 2;
+  if (hint.reachable === true && hint.kind === "tailscale")
+    return 3;
+  if (hint.reachable === false)
+    return 8;
+  if (hint.kind === "ssh")
+    return 4;
+  if (hint.kind === "lan")
+    return 5;
+  if (hint.kind === "tailscale")
+    return 6;
+  return 9;
+}
+function selectRouteHint(hints) {
+  return [...hints].sort((left, right) => routeRank(left) - routeRank(right))[0] ?? null;
+}
+function buildEntry(input) {
+  const manifest = input.manifest;
+  const peer = input.peer;
+  const hints = routeHints({
+    machineId: input.machineId,
+    localMachineId: input.localMachineId,
+    manifest,
+    peer
   });
-  return probe.status === 0;
+  const selectedRoute = selectRouteHint(hints);
+  const route = selectedRoute?.kind === "ssh" ? "ssh" : selectedRoute?.kind ?? "unknown";
+  return {
+    machine_id: input.machineId,
+    hostname: manifest?.hostname ?? peer?.HostName ?? null,
+    platform: manifest?.platform ?? (peer?.OS ? normalizePlatform2(peer.OS) : null),
+    os: peer?.OS ?? null,
+    user: typeof manifest?.metadata?.user === "string" ? manifest.metadata.user : null,
+    workspace_path: manifest?.workspacePath ?? null,
+    manifest_declared: Boolean(manifest),
+    heartbeat_status: input.heartbeat?.status ?? "unknown",
+    last_heartbeat_at: input.heartbeat?.updated_at ?? null,
+    tailscale: {
+      dns_name: manifest?.tailscaleName ?? peer?.DNSName?.replace(/\.$/, "") ?? null,
+      ips: peer?.TailscaleIPs ?? [],
+      online: peer?.Online ?? null,
+      active: peer?.Active ?? null,
+      last_seen: peer?.LastSeen ?? null
+    },
+    ssh: {
+      address: manifest?.sshAddress ?? null,
+      route,
+      command_target: selectedRoute?.target ?? null
+    },
+    route_hints: hints,
+    tags: manifest?.tags ?? [],
+    metadata: manifest?.metadata ?? {}
+  };
 }
-function resolveSshTarget(machineId) {
-  const machine = getManifestMachine(machineId);
-  if (!machine) {
-    throw new Error(`Machine not found in manifest: ${machineId}`);
+function discoverMachineTopology(options = {}) {
+  const now = options.now ?? new Date;
+  const runner = options.runner ?? defaultRunner;
+  const warnings = [];
+  const manifest = readManifest();
+  const heartbeats = listHeartbeats();
+  const heartbeatByMachine = new Map(heartbeats.map((heartbeat) => [heartbeat.machine_id, heartbeat]));
+  const localMachineId = getLocalMachineId();
+  const peers = options.includeTailscale === false ? new Map : loadTailscalePeers(runner, warnings);
+  const machineIds = new Set([
+    localMachineId,
+    ...manifest.machines.map((machine) => machine.id),
+    ...heartbeats.map((heartbeat) => heartbeat.machine_id),
+    ...peers.keys()
+  ]);
+  const manifestById = new Map(manifest.machines.map((machine) => [machine.id, machine]));
+  const machines = [...machineIds].sort().map((machineId) => {
+    const manifestMachine = manifestById.get(machineId);
+    return buildEntry({
+      machineId,
+      localMachineId,
+      manifest: manifestMachine,
+      peer: findTailscalePeer(manifestMachine ?? null, machineId, peers),
+      heartbeat: heartbeatByMachine.get(machineId)
+    });
+  });
+  return {
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: {
+      name: MACHINES_PACKAGE_NAME,
+      version: getPackageVersion()
+    },
+    capabilities: {
+      topology: true,
+      compatibility: true,
+      route_resolution: true,
+      cli_json_fallback: true
+    },
+    generated_at: now.toISOString(),
+    local_machine_id: localMachineId,
+    local_hostname: hostname3(),
+    current_platform: normalizePlatform2(),
+    manifest_path_known: existsSync4(getManifestPath()),
+    machines,
+    warnings
+  };
+}
+function normalizeMachineAlias(value) {
+  return value.trim().replace(/\.$/, "").toLowerCase();
+}
+function routeTargetMatches(machine, requested) {
+  const normalized = normalizeMachineAlias(requested);
+  const values = [
+    machine.ssh.address,
+    machine.ssh.command_target,
+    machine.tailscale.dns_name,
+    machine.tailscale.dns_name?.split(".")[0],
+    ...machine.tailscale.ips,
+    ...machine.route_hints.map((hint) => hint.target),
+    ...machine.route_hints.map((hint) => hint.target.split("@").pop() ?? hint.target)
+  ].filter((value) => Boolean(value));
+  return values.some((value) => normalizeMachineAlias(value) === normalized);
+}
+function findRouteMachine(topology, requestedMachineId) {
+  const requested = normalizeMachineAlias(requestedMachineId);
+  if (requested === "local" || requested === "localhost" || requested === normalizeMachineAlias(hostname3()) || requested === normalizeMachineAlias(topology.local_machine_id)) {
+    return {
+      machine: topology.machines.find((machine) => machine.machine_id === topology.local_machine_id) ?? null,
+      matchedBy: "local_alias"
+    };
   }
-  const current = detectCurrentMachineManifest();
-  if (machine.id === current.id) {
+  const machineIdMatch = topology.machines.find((machine) => normalizeMachineAlias(machine.machine_id) === requested);
+  if (machineIdMatch)
+    return { machine: machineIdMatch, matchedBy: "machine_id" };
+  const hostnameMatch = topology.machines.find((machine) => machine.hostname && normalizeMachineAlias(machine.hostname) === requested);
+  if (hostnameMatch)
+    return { machine: hostnameMatch, matchedBy: "hostname" };
+  const tailscaleMatch = topology.machines.find((machine) => {
+    if (!machine.tailscale.dns_name)
+      return false;
+    const dns = normalizeMachineAlias(machine.tailscale.dns_name);
+    return dns === requested || dns.split(".")[0] === requested;
+  });
+  if (tailscaleMatch)
+    return { machine: tailscaleMatch, matchedBy: "tailscale" };
+  const routeMatch = topology.machines.find((machine) => routeTargetMatches(machine, requestedMachineId));
+  if (routeMatch)
+    return { machine: routeMatch, matchedBy: "route_target" };
+  return { machine: null, matchedBy: null };
+}
+function routeConfidence(input) {
+  if (input.matchedBy === "local_alias")
+    return "exact";
+  if (input.hint?.kind === "local")
+    return "exact";
+  if (input.hint?.reachable === true)
+    return "high";
+  if (input.machine.manifest_declared && (input.hint?.kind === "ssh" || input.hint?.kind === "lan"))
+    return "medium";
+  if (input.hint)
+    return "low";
+  return "none";
+}
+function resolveMachineRoute(machineId, options = {}) {
+  const topology = options.topology ?? discoverMachineTopology(options);
+  const warnings = [...topology.warnings];
+  const { machine, matchedBy } = findRouteMachine(topology, machineId);
+  const generatedAt = (options.now ?? new Date).toISOString();
+  if (!machine) {
+    warnings.push(`machine_not_found:${machineId}`);
     return {
-      machineId,
-      target: "localhost",
-      route: "local"
+      schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+      package: { name: MACHINES_PACKAGE_NAME, version: getPackageVersion() },
+      ok: false,
+      machine_id: null,
+      requested_machine_id: machineId,
+      generated_at: generatedAt,
+      route: "unknown",
+      source: "unknown",
+      target: null,
+      command_target: null,
+      confidence: "none",
+      local: false,
+      evidence: {
+        topology: true,
+        matched_by: null,
+        manifest_declared: null,
+        heartbeat_status: null,
+        tailscale_online: null,
+        selected_hint: null
+      },
+      warnings
     };
   }
-  const lanTarget = machine.sshAddress || machine.hostname || machine.id;
-  const tailscaleTarget = machine.tailscaleName || machine.hostname || machine.id;
-  const route = isReachable(lanTarget) ? "lan" : "tailscale";
+  const selectedHint = selectRouteHint(machine.route_hints);
+  const route = selectedHint?.kind ?? machine.ssh.route ?? "unknown";
+  const local = route === "local" || machine.machine_id === topology.local_machine_id;
   return {
-    machineId,
-    target: route === "lan" ? lanTarget : tailscaleTarget,
-    route
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: topology.package,
+    ok: Boolean(selectedHint?.target),
+    machine_id: machine.machine_id,
+    requested_machine_id: machineId,
+    generated_at: generatedAt,
+    route,
+    source: route,
+    target: selectedHint?.target ?? null,
+    command_target: selectedHint?.target ?? null,
+    confidence: routeConfidence({ machine, hint: selectedHint, matchedBy }),
+    local,
+    evidence: {
+      topology: true,
+      matched_by: matchedBy,
+      manifest_declared: machine.manifest_declared,
+      heartbeat_status: machine.heartbeat_status,
+      tailscale_online: machine.tailscale.online,
+      selected_hint: selectedHint
+    },
+    warnings
+  };
+}
+
+// src/commands/ssh.ts
+function resolveSshTarget(machineId, options = {}) {
+  const resolved = resolveMachineRoute(machineId, options);
+  if (!resolved.ok || !resolved.target) {
+    throw new Error(`Machine route not found: ${machineId}`);
+  }
+  if (resolved.route !== "local" && resolved.route !== "lan" && resolved.route !== "tailscale" && resolved.route !== "ssh") {
+    throw new Error(`Machine route is not SSH-capable: ${machineId}`);
+  }
+  return {
+    machineId: resolved.machine_id ?? machineId,
+    target: resolved.target,
+    route: resolved.route,
+    confidence: resolved.confidence,
+    warnings: resolved.warnings
   };
 }
-function buildSshCommand(machineId, remoteCommand) {
-  const resolved = resolveSshTarget(machineId);
+function buildSshCommand(machineId, remoteCommand, options = {}) {
+  const resolved = resolveSshTarget(machineId, options);
   return remoteCommand ? `ssh ${resolved.target} ${JSON.stringify(remoteCommand)}` : `ssh ${resolved.target}`;
 }
 
 // src/remote.ts
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function machineIsLocal(machineId, localMachineId) {
+  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname4();
+}
+function resolveMachineCommand(machineId, command, localMachineId = getLocalMachineId()) {
+  if (machineIsLocal(machineId, localMachineId)) {
+    return { source: "local", shellCommand: command };
+  }
+  try {
+    return {
+      source: resolveSshTarget(machineId).route,
+      shellCommand: buildSshCommand(machineId, command)
+    };
+  } catch (error) {
+    const message = String(error.message ?? error);
+    if (message.includes("Machine route not found") || message.includes("Machine not found in manifest")) {
+      return { source: "ssh", shellCommand: `ssh ${shellQuote(machineId)} ${shellQuote(command)}` };
+    }
+    throw error;
+  }
+}
 function runMachineCommand(machineId, command) {
-  const localMachineId = getLocalMachineId();
-  const isLocal = machineId === localMachineId;
-  const route = isLocal ? "local" : resolveSshTarget(machineId).route;
-  const shellCommand = isLocal ? command : buildSshCommand(machineId, command);
-  const result = spawnSync2("bash", ["-c", shellCommand], {
+  const resolved = resolveMachineCommand(machineId, command);
+  const result = spawnSync2("bash", ["-c", resolved.shellCommand], {
     encoding: "utf8",
     env: process.env
   });
   return {
     machineId,
-    source: route,
+    source: resolved.source,
     stdout: result.stdout || "",
     stderr: result.stderr || "",
     exitCode: result.status ?? 1
@@ -4393,7 +4729,7 @@ function getAppManager(machine, app) {
     return "winget";
   return "apt";
 }
-function shellQuote(value) {
+function shellQuote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function buildAppCommand(machine, app) {
@@ -4414,7 +4750,7 @@ function buildAppCommand(machine, app) {
   return `sudo apt-get install -y ${packageName}`;
 }
 function buildAppProbeCommand(machine, app) {
-  const packageName = shellQuote(getPackageName(app));
+  const packageName = shellQuote2(getPackageName(app));
   const manager = getAppManager(machine, app);
   if (manager === "custom") {
     return `if command -v ${packageName} >/dev/null 2>&1; then printf 'installed=1\\nversion=custom\\n'; else printf 'installed=0\\n'; fi`;
@@ -4519,7 +4855,7 @@ function runAppsInstall(machineId, options = {}) {
 }
 
 // src/commands/cert.ts
-import { homedir as homedir3, platform as platform2 } from "os";
+import { homedir as homedir3, platform as platform3 } from "os";
 import { join as join4 } from "path";
 function quote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -4535,7 +4871,7 @@ function buildCertPlan(domains) {
   const certPath = join4(certDir(), `${primary}.pem`);
   const keyPath = join4(certDir(), `${primary}-key.pem`);
   const steps = [];
-  if (platform2() === "darwin") {
+  if (platform3() === "darwin") {
     steps.push({
       id: "mkcert-install-macos",
       title: "Install mkcert on macOS",
@@ -4597,14 +4933,14 @@ function runCertPlan(domains, options = {}) {
 }
 
 // src/commands/dns.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { join as join5 } from "path";
 function getDnsPath() {
   return join5(getDataDir(), "dns.json");
 }
 function readMappings() {
   const path = getDnsPath();
-  if (!existsSync4(path))
+  if (!existsSync5(path))
     return [];
   return JSON.parse(readFileSync3(path, "utf8"));
 }
@@ -4908,7 +5244,7 @@ function runTailscaleInstall(machineId, options = {}) {
 }
 
 // src/commands/notifications.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 var notificationChannelSchema = exports_external.object({
   id: exports_external.string(),
   type: exports_external.enum(["email", "webhook", "command"]),
@@ -4924,10 +5260,10 @@ var notificationConfigSchema = exports_external.object({
 function sortChannels(channels) {
   return [...channels].sort((left, right) => left.id.localeCompare(right.id));
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function hasCommand(binary) {
+function hasCommand2(binary) {
   const result = Bun.spawnSync(["bash", "-lc", `command -v ${binary} >/dev/null 2>&1`], {
     stdout: "ignore",
     stderr: "ignore",
@@ -4952,7 +5288,7 @@ Content-Type: text/plain; charset=utf-8
 
 ${message}
 `;
-  if (hasCommand("sendmail")) {
+  if (hasCommand2("sendmail")) {
     const result = Bun.spawnSync(["bash", "-lc", "sendmail -t"], {
       stdin: new TextEncoder().encode(body),
       stdout: "pipe",
@@ -4970,8 +5306,8 @@ ${message}
       detail: `Delivered via sendmail to ${channel.target}`
     };
   }
-  if (hasCommand("mail")) {
-    const command = `printf %s ${shellQuote2(message)} | mail -s ${shellQuote2(subject)} ${shellQuote2(channel.target)}`;
+  if (hasCommand2("mail")) {
+    const command = `printf %s ${shellQuote3(message)} | mail -s ${shellQuote3(subject)} ${shellQuote3(channel.target)}`;
     const result = Bun.spawnSync(["bash", "-lc", command], {
       stdout: "pipe",
       stderr: "pipe",
@@ -5064,7 +5400,7 @@ function getDefaultNotificationConfig() {
   };
 }
 function readNotificationConfig(path = getNotificationsPath()) {
-  if (!existsSync5(path)) {
+  if (!existsSync6(path)) {
     return getDefaultNotificationConfig();
   }
   return notificationConfigSchema.parse(JSON.parse(readFileSync4(path, "utf8")));
@@ -5596,7 +5932,7 @@ function runSetup(machineId, options = {}) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync6, lstatSync, readFileSync as readFileSync5, symlinkSync, copyFileSync } from "fs";
+import { existsSync as existsSync7, lstatSync, readFileSync as readFileSync5, symlinkSync, copyFileSync } from "fs";
 function quote4(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -5644,8 +5980,8 @@ function detectPackageActions(machine) {
 }
 function detectFileActions(machine) {
   return (machine.files || []).map((file, index) => {
-    const sourceExists = existsSync6(file.source);
-    const targetExists = existsSync6(file.target);
+    const sourceExists = existsSync7(file.source);
+    const targetExists = existsSync7(file.target);
     let status = "missing";
     if (sourceExists && targetExists) {
       if (file.mode === "symlink") {
@@ -5757,183 +6093,6 @@ function getAgentStatus(machineId = getLocalMachineId()) {
   }));
 }
 
-// src/topology.ts
-import { existsSync as existsSync7 } from "fs";
-import { arch as arch2, hostname as hostname3, platform as platform3, userInfo as userInfo2 } from "os";
-import { spawnSync as spawnSync4 } from "child_process";
-function normalizePlatform2(value = platform3()) {
-  const normalized = value.toLowerCase();
-  if (normalized === "darwin" || normalized === "macos")
-    return "macos";
-  if (normalized === "win32" || normalized === "windows")
-    return "windows";
-  if (normalized === "linux")
-    return "linux";
-  return value;
-}
-function defaultRunner(command) {
-  const result = spawnSync4("bash", ["-c", command], {
-    encoding: "utf8",
-    env: process.env
-  });
-  return {
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    exitCode: result.status ?? 1
-  };
-}
-function hasCommand2(command, runner) {
-  return runner(`command -v ${command} >/dev/null 2>&1`).exitCode === 0;
-}
-function parseTailscaleStatus(raw) {
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object")
-      return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-function loadTailscalePeers(runner, warnings) {
-  const peers = new Map;
-  if (!hasCommand2("tailscale", runner)) {
-    warnings.push("tailscale_not_available");
-    return peers;
-  }
-  const result = runner("tailscale status --json");
-  if (result.exitCode !== 0) {
-    warnings.push(`tailscale_status_failed:${result.stderr.trim() || result.exitCode}`);
-    return peers;
-  }
-  const status = parseTailscaleStatus(result.stdout);
-  if (!status) {
-    warnings.push("tailscale_status_invalid_json");
-    return peers;
-  }
-  const addPeer = (peer) => {
-    if (!peer)
-      return;
-    const id = peer.HostName || peer.DNSName?.split(".")[0];
-    if (id)
-      peers.set(id, peer);
-  };
-  addPeer(status.Self);
-  for (const peer of Object.values(status.Peer ?? {}))
-    addPeer(peer);
-  return peers;
-}
-function machineKeys(machine) {
-  return [
-    machine.id,
-    machine.hostname,
-    machine.tailscaleName?.split(".")[0],
-    machine.tailscaleName,
-    machine.sshAddress?.split("@").pop()
-  ].filter((value) => Boolean(value));
-}
-function findTailscalePeer(machine, machineId, peers) {
-  if (machine) {
-    for (const key of machineKeys(machine)) {
-      const peer = peers.get(key) ?? peers.get(key.replace(/\.$/, ""));
-      if (peer)
-        return peer;
-    }
-  }
-  return peers.get(machineId) ?? null;
-}
-function routeHints(input) {
-  const hints = [];
-  if (input.machineId === input.localMachineId) {
-    hints.push({ kind: "local", target: "localhost", reachable: true });
-  }
-  if (input.manifest?.sshAddress) {
-    hints.push({ kind: "ssh", target: input.manifest.sshAddress, reachable: null });
-  }
-  if (input.manifest?.hostname) {
-    hints.push({ kind: "lan", target: input.manifest.hostname, reachable: null });
-  }
-  const tailscaleTarget = input.manifest?.tailscaleName ?? input.peer?.DNSName ?? input.peer?.TailscaleIPs?.[0];
-  if (tailscaleTarget) {
-    hints.push({ kind: "tailscale", target: tailscaleTarget.replace(/\.$/, ""), reachable: input.peer?.Online ?? null });
-  }
-  return hints;
-}
-function buildEntry(input) {
-  const manifest = input.manifest;
-  const peer = input.peer;
-  const hints = routeHints({
-    machineId: input.machineId,
-    localMachineId: input.localMachineId,
-    manifest,
-    peer
-  });
-  const selectedRoute = hints.find((hint) => hint.kind === "local") ?? hints.find((hint) => hint.kind === "ssh") ?? hints.find((hint) => hint.kind === "lan") ?? hints.find((hint) => hint.kind === "tailscale");
-  const route = selectedRoute?.kind === "ssh" ? "lan" : selectedRoute?.kind ?? "unknown";
-  return {
-    machine_id: input.machineId,
-    hostname: manifest?.hostname ?? peer?.HostName ?? null,
-    platform: manifest?.platform ?? (peer?.OS ? normalizePlatform2(peer.OS) : null),
-    os: peer?.OS ?? null,
-    user: typeof manifest?.metadata?.user === "string" ? manifest.metadata.user : null,
-    workspace_path: manifest?.workspacePath ?? null,
-    manifest_declared: Boolean(manifest),
-    heartbeat_status: input.heartbeat?.status ?? "unknown",
-    last_heartbeat_at: input.heartbeat?.updated_at ?? null,
-    tailscale: {
-      dns_name: manifest?.tailscaleName ?? peer?.DNSName?.replace(/\.$/, "") ?? null,
-      ips: peer?.TailscaleIPs ?? [],
-      online: peer?.Online ?? null,
-      active: peer?.Active ?? null,
-      last_seen: peer?.LastSeen ?? null
-    },
-    ssh: {
-      address: manifest?.sshAddress ?? null,
-      route,
-      command_target: selectedRoute?.target ?? null
-    },
-    route_hints: hints,
-    tags: manifest?.tags ?? [],
-    metadata: manifest?.metadata ?? {}
-  };
-}
-function discoverMachineTopology(options = {}) {
-  const now = options.now ?? new Date;
-  const runner = options.runner ?? defaultRunner;
-  const warnings = [];
-  const manifest = readManifest();
-  const heartbeats = listHeartbeats();
-  const heartbeatByMachine = new Map(heartbeats.map((heartbeat) => [heartbeat.machine_id, heartbeat]));
-  const localMachineId = getLocalMachineId();
-  const peers = options.includeTailscale === false ? new Map : loadTailscalePeers(runner, warnings);
-  const machineIds = new Set([
-    localMachineId,
-    ...manifest.machines.map((machine) => machine.id),
-    ...heartbeats.map((heartbeat) => heartbeat.machine_id),
-    ...peers.keys()
-  ]);
-  const manifestById = new Map(manifest.machines.map((machine) => [machine.id, machine]));
-  const machines = [...machineIds].sort().map((machineId) => {
-    const manifestMachine = manifestById.get(machineId);
-    return buildEntry({
-      machineId,
-      localMachineId,
-      manifest: manifestMachine,
-      peer: findTailscalePeer(manifestMachine ?? null, machineId, peers),
-      heartbeat: heartbeatByMachine.get(machineId)
-    });
-  });
-  return {
-    generated_at: now.toISOString(),
-    local_machine_id: localMachineId,
-    local_hostname: hostname3(),
-    current_platform: normalizePlatform2(),
-    manifest_path_known: existsSync7(getManifestPath()),
-    machines,
-    warnings
-  };
-}
-
 // src/compatibility.ts
 var DEFAULT_COMMANDS = [
   { command: "bun", required: true },
@@ -5942,7 +6101,7 @@ var DEFAULT_COMMANDS = [
 function defaultPackages() {
   return [{ name: "@hasna/machines", command: "machines", expectedVersion: getPackageVersion(), required: true }];
 }
-function shellQuote3(value) {
+function shellQuote4(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function commandId(value) {
@@ -5993,7 +6152,7 @@ function defaultRunner2(machineId, command) {
   return runMachineCommand(machineId, command);
 }
 function inspectCommand(machineId, spec, runner) {
-  const command = shellQuote3(spec.command);
+  const command = shellQuote4(spec.command);
   const versionArgs = spec.versionArgs ?? "--version";
   const script = [
     `cmd=${command}`,
@@ -6022,7 +6181,7 @@ function fieldCommand(field) {
 }
 function inspectWorkspace(machineId, spec, runner) {
   const script = [
-    `path=${shellQuote3(spec.path)}`,
+    `path=${shellQuote4(spec.path)}`,
     'printf "exists=%s\\n" "$(test -d "$path" && printf yes || printf no)"',
     'pkg="$path/package.json"',
     'printf "package_json=%s\\n" "$(test -f "$pkg" && printf yes || printf no)"',
@@ -6160,6 +6319,17 @@ function checkMachineCompatibility(options = {}) {
     fail: checks.filter((check2) => check2.status === "fail").length
   };
   return {
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: {
+      name: MACHINES_PACKAGE_NAME,
+      version: getPackageVersion()
+    },
+    capabilities: {
+      topology: true,
+      compatibility: true,
+      route_resolution: true,
+      cli_json_fallback: true
+    },
     ok: summary.fail === 0,
     machine_id: machineId,
     source: checks[0]?.source ?? "local",
@@ -6579,8 +6749,11 @@ function createMcpServer(version) {
   }));
   server.tool("machines_install_tailscale_preview", "Preview Tailscale install steps for a machine.", { machine_id: exports_external.string().optional().describe("Machine identifier") }, async ({ machine_id }) => ({ content: [{ type: "text", text: JSON.stringify(buildTailscaleInstallPlan(machine_id), null, 2) }] }));
   server.tool("machines_install_tailscale_apply", "Execute Tailscale install steps for a machine.", { machine_id: exports_external.string().optional().describe("Machine identifier"), yes: exports_external.boolean().describe("Confirmation flag for execution") }, async ({ machine_id, yes }) => ({ content: [{ type: "text", text: JSON.stringify(runTailscaleInstall(machine_id, { apply: true, yes }), null, 2) }] }));
+  server.tool("machines_route_resolve", "Resolve the best route for a machine using manifest, heartbeat, SSH, LAN, and Tailscale topology.", { machine_id: exports_external.string().describe("Machine identifier"), include_tailscale: exports_external.boolean().optional().describe("Whether to probe tailscale status --json") }, async ({ machine_id, include_tailscale }) => ({
+    content: [{ type: "text", text: JSON.stringify(resolveMachineRoute(machine_id, { includeTailscale: include_tailscale !== false }), null, 2) }]
+  }));
   server.tool("machines_ssh_resolve", "Resolve the best SSH route for a machine.", { machine_id: exports_external.string().describe("Machine identifier"), remote_command: exports_external.string().optional().describe("Optional remote command") }, async ({ machine_id, remote_command }) => ({
-    content: [{ type: "text", text: JSON.stringify({ resolved: resolveSshTarget(machine_id), command: buildSshCommand(machine_id, remote_command) }, null, 2) }]
+    content: [{ type: "text", text: JSON.stringify({ resolved: resolveMachineRoute(machine_id), command: buildSshCommand(machine_id, remote_command) }, null, 2) }]
   }));
   server.tool("machines_ports", "List listening ports on a machine.", { machine_id: exports_external.string().optional().describe("Machine identifier") }, async ({ machine_id }) => ({
     content: [{ type: "text", text: JSON.stringify(listPorts(machine_id), null, 2) }]