@hasna/machines 0.0.16 → 0.0.18

package/dist/cli/index.js

@@ -7573,57 +7573,377 @@ function diffMachines(leftMachineId, rightMachineId) {
 // src/remote.ts
 init_db();
 import { spawnSync as spawnSync2 } from "child_process";
-import { hostname as hostname3 } from "os";
+import { hostname as hostname4 } from "os";
 
-// src/commands/ssh.ts
+// src/topology.ts
+init_db();
+import { existsSync as existsSync5 } from "fs";
+import { arch as arch2, hostname as hostname3, platform as platform3, userInfo as userInfo2 } from "os";
 import { spawnSync } from "child_process";
+init_paths();
+var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
+var MACHINES_PACKAGE_NAME = "@hasna/machines";
+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 = 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 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 });
   }
-  const probe = spawnSync("bash", ["-lc", `getent hosts ${host} >/dev/null 2>&1 || ping -c 1 -W 1 ${host} >/dev/null 2>&1`], {
-    stdio: "ignore"
+  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: existsSync5(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 shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+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);
-  return remoteCommand ? `ssh ${resolved.target} ${JSON.stringify(remoteCommand)}` : `ssh ${resolved.target}`;
+function buildSshCommand(machineId, remoteCommand, options = {}) {
+  const resolved = resolveSshTarget(machineId, options);
+  return remoteCommand ? `ssh ${resolved.target} ${shellQuote(remoteCommand)}` : `ssh ${resolved.target}`;
 }
 
 // src/remote.ts
-function shellQuote(value) {
+function shellQuote2(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function machineIsLocal(machineId, localMachineId) {
-  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname3();
+  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname4();
 }
 function resolveMachineCommand(machineId, command, localMachineId = getLocalMachineId()) {
   if (machineIsLocal(machineId, localMachineId)) {
@@ -7635,8 +7955,9 @@ function resolveMachineCommand(machineId, command, localMachineId = getLocalMach
       shellCommand: buildSshCommand(machineId, command)
     };
   } catch (error) {
-    if (String(error.message ?? error).includes("Machine not found in manifest")) {
-      return { source: "ssh", shellCommand: `ssh ${shellQuote(machineId)} ${shellQuote(command)}` };
+    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 ${shellQuote2(machineId)} ${shellQuote2(command)}` };
     }
     throw error;
   }
@@ -7669,7 +7990,7 @@ function getAppManager(machine, app) {
     return "winget";
   return "apt";
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function buildAppCommand(machine, app) {
@@ -7690,7 +8011,7 @@ function buildAppCommand(machine, app) {
   return `sudo apt-get install -y ${packageName}`;
 }
 function buildAppProbeCommand(machine, app) {
-  const packageName = shellQuote2(getPackageName(app));
+  const packageName = shellQuote3(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`;
@@ -7968,7 +8289,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";
 init_paths();
 var notificationChannelSchema = exports_external.object({
   id: exports_external.string(),
@@ -7985,10 +8306,10 @@ var notificationConfigSchema = exports_external.object({
 function sortChannels(channels) {
   return [...channels].sort((left, right) => left.id.localeCompare(right.id));
 }
-function shellQuote3(value) {
+function shellQuote4(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",
@@ -8013,7 +8334,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",
@@ -8031,8 +8352,8 @@ ${message}
       detail: `Delivered via sendmail to ${channel.target}`
     };
   }
-  if (hasCommand("mail")) {
-    const command = `printf %s ${shellQuote3(message)} | mail -s ${shellQuote3(subject)} ${shellQuote3(channel.target)}`;
+  if (hasCommand2("mail")) {
+    const command = `printf %s ${shellQuote4(message)} | mail -s ${shellQuote4(subject)} ${shellQuote4(channel.target)}`;
     const result = Bun.spawnSync(["bash", "-lc", command], {
       stdout: "pipe",
       stderr: "pipe",
@@ -8125,7 +8446,7 @@ function getDefaultNotificationConfig() {
   };
 }
 function readNotificationConfig(path = getNotificationsPath()) {
-  if (!existsSync5(path)) {
+  if (!existsSync6(path)) {
     return getDefaultNotificationConfig();
   }
   return notificationConfigSchema.parse(JSON.parse(readFileSync4(path, "utf8")));
@@ -8271,7 +8592,7 @@ function listPorts(machineId) {
 }
 
 // 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";
 init_paths();
 init_db();
 function quote4(value) {
@@ -8321,8 +8642,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") {
@@ -8458,185 +8779,6 @@ function getStatus() {
   };
 }
 
-// src/topology.ts
-init_db();
-import { existsSync as existsSync7 } from "fs";
-import { arch as arch2, hostname as hostname4, platform as platform3, userInfo as userInfo2 } from "os";
-import { spawnSync as spawnSync4 } from "child_process";
-init_paths();
-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: hostname4(),
-    current_platform: normalizePlatform2(),
-    manifest_path_known: existsSync7(getManifestPath()),
-    machines,
-    warnings
-  };
-}
-
 // src/compatibility.ts
 init_db();
 var DEFAULT_COMMANDS = [
@@ -8646,7 +8788,7 @@ var DEFAULT_COMMANDS = [
 function defaultPackages() {
   return [{ name: "@hasna/machines", command: "machines", expectedVersion: getPackageVersion(), required: true }];
 }
-function shellQuote4(value) {
+function shellQuote5(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function commandId(value) {
@@ -8697,7 +8839,7 @@ function defaultRunner2(machineId, command) {
   return runMachineCommand(machineId, command);
 }
 function inspectCommand(machineId, spec, runner) {
-  const command = shellQuote4(spec.command);
+  const command = shellQuote5(spec.command);
   const versionArgs = spec.versionArgs ?? "--version";
   const script = [
     `cmd=${command}`,
@@ -8726,7 +8868,7 @@ function fieldCommand(field) {
 }
 function inspectWorkspace(machineId, spec, runner) {
   const script = [
-    `path=${shellQuote4(spec.path)}`,
+    `path=${shellQuote5(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)"',
@@ -8864,6 +9006,17 @@ function checkMachineCompatibility(options = {}) {
     fail: checks.filter((check) => check.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",
@@ -10333,10 +10486,13 @@ function parsePackageSpec(value) {
   };
 }
 function parseWorkspaceSpec(value) {
-  const [label, path] = value.includes("=") ? value.split(/=(.*)/s).filter(Boolean) : ["workspace", value];
+  const [label, rest] = value.includes("=") ? value.split(/=(.*)/s).filter(Boolean) : ["workspace", value];
+  const [path, expectedPackageName, expectedVersion] = rest.split(":");
   return {
     label,
     path,
+    expectedPackageName: expectedPackageName || undefined,
+    expectedVersion: expectedVersion || undefined,
     required: true
   };
 }
@@ -10497,7 +10653,7 @@ program2.command("topology").description("Discover local, manifest, heartbeat, S
     console.log(`${machine.machine_id.padEnd(18)} ${String(machine.platform || "unknown").padEnd(8)} ${machine.heartbeat_status.padEnd(8)} ${route}`);
   }
 });
-program2.command("compatibility").description("Check remote package, command, and workspace compatibility for open-* consumers").option("--machine <id>", "Machine identifier").option("--command <command...>", "Required command or command:expectedVersion").option("--package <spec...>", "Required package as name[:command[:expectedVersion]]").option("--workspace <spec...>", "Required workspace as label=/path or /path").option("-j, --json", "Print JSON output", false).action((options) => {
+program2.command("compatibility").description("Check remote package, command, and workspace compatibility for open-* consumers").option("--machine <id>", "Machine identifier").option("--command <command...>", "Required command or command:expectedVersion").option("--package <spec...>", "Required package as name[:command[:expectedVersion]]").option("--workspace <spec...>", "Required workspace as label=/path[:expectedPackageName[:expectedVersion]] or /path[:expectedPackageName[:expectedVersion]]").option("-j, --json", "Print JSON output", false).action((options) => {
   const result = checkMachineCompatibility({
     machineId: options.machine,
     commands: options.command?.map(parseCommandSpec),
@@ -10650,9 +10806,26 @@ program2.command("install-tailscale").description("Install Tailscale on a machin
   const result = options.apply ? runTailscaleInstall(options.machine, { apply: true, yes: options.yes }) : buildTailscaleInstallPlan(options.machine);
   console.log(JSON.stringify(result, null, 2));
 });
+program2.command("route").description("Resolve the best route for a machine").requiredOption("--machine <id>", "Machine identifier").option("--no-tailscale", "Skip tailscale status probing").option("--cmd <command>", "Remote command to run").option("-j, --json", "Print JSON output", false).action((options) => {
+  const topology = discoverMachineTopology({ includeTailscale: options.tailscale !== false });
+  const resolved = resolveMachineRoute(options.machine, { topology });
+  const command = resolved.ok && resolved.target ? resolved.route === "local" ? options.cmd ?? null : buildSshCommand(options.machine, options.cmd, { topology }) : null;
+  const payload = { ...resolved, command };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!resolved.ok) {
+    console.error(source_default.red(resolved.warnings.join("; ") || `No route found for ${options.machine}`));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(command ?? `${resolved.route}:${resolved.target}`);
+});
 program2.command("ssh").description("Choose the best SSH route for a machine").requiredOption("--machine <id>", "Machine identifier").option("--cmd <command>", "Remote command to run").option("-j, --json", "Print JSON output", false).action((options) => {
   if (options.json) {
-    console.log(JSON.stringify(resolveSshTarget(options.machine), null, 2));
+    const resolved = resolveMachineRoute(options.machine);
+    console.log(JSON.stringify({ resolved, command: resolved.ok ? buildSshCommand(options.machine, options.cmd) : null }, null, 2));
     return;
   }
   console.log(buildSshCommand(options.machine, options.cmd));