@hasna/machines 0.0.16 → 0.0.18

package/dist/index.js

@@ -11085,9 +11085,31 @@ function detectCurrentMachineManifest() {
   };
 }
 // src/topology.ts
-import { existsSync as existsSync3 } from "fs";
+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";
+
+// src/version.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function getPackageVersion() {
+  try {
+    const here = dirname3(fileURLToPath(import.meta.url));
+    const candidates = [join2(here, "..", "package.json"), join2(here, "..", "..", "package.json")];
+    const pkgPath = candidates.find((candidate) => existsSync3(candidate));
+    if (!pkgPath) {
+      return "0.0.0";
+    }
+    return JSON.parse(readFileSync2(pkgPath, "utf8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/topology.ts
+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")
@@ -11169,16 +11191,26 @@ function findTailscalePeer(machine, machineId, peers) {
   }
   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 manifestHostReachable(target) {
+  const overrides = envReachableHosts();
+  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: null });
+    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: null });
+    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) {
@@ -11186,6 +11218,28 @@ function routeHints(input) {
   }
   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;
@@ -11195,8 +11249,8 @@ function buildEntry(input) {
     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";
+  const selectedRoute = selectRouteHint(hints);
+  const route = selectedRoute?.kind === "ssh" ? "ssh" : selectedRoute?.kind ?? "unknown";
   return {
     machine_id: input.machineId,
     hostname: manifest?.hostname ?? peer?.HostName ?? null,
@@ -11251,15 +11305,140 @@ function discoverMachineTopology(options = {}) {
     });
   });
   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: existsSync3(getManifestPath()),
+    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 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 {
+      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 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 {
+    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
+  };
+}
 function getLocalMachineTopology(options = {}) {
   const topology = discoverMachineTopology(options);
   return topology.machines.find((machine) => machine.machine_id === topology.local_machine_id) ?? {
@@ -11280,54 +11459,36 @@ function getLocalMachineTopology(options = {}) {
   };
 }
 // src/remote.ts
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { hostname as hostname4 } from "os";
 
 // src/commands/ssh.ts
-import { spawnSync as spawnSync2 } from "child_process";
-function envReachableHosts() {
-  const raw = process.env["HASNA_MACHINES_REACHABLE_HOSTS"];
-  return new Set((raw || "").split(",").map((value) => value.trim()).filter(Boolean));
-}
-function isReachable(host) {
-  const overrides = envReachableHosts();
-  if (overrides.size > 0) {
-    return overrides.has(host);
-  }
-  const probe = spawnSync2("bash", ["-lc", `getent hosts ${host} >/dev/null 2>&1 || ping -c 1 -W 1 ${host} >/dev/null 2>&1`], {
-    stdio: "ignore"
-  });
-  return probe.status === 0;
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
-function resolveSshTarget(machineId) {
-  const machine = getManifestMachine(machineId);
-  if (!machine) {
-    throw new Error(`Machine not found in manifest: ${machineId}`);
+function resolveSshTarget(machineId, options = {}) {
+  const resolved = resolveMachineRoute(machineId, options);
+  if (!resolved.ok || !resolved.target) {
+    throw new Error(`Machine route not found: ${machineId}`);
   }
-  const current = detectCurrentMachineManifest();
-  if (machine.id === current.id) {
-    return {
-      machineId,
-      target: "localhost",
-      route: "local"
-    };
+  if (resolved.route !== "local" && resolved.route !== "lan" && resolved.route !== "tailscale" && resolved.route !== "ssh") {
+    throw new Error(`Machine route is not SSH-capable: ${machineId}`);
   }
-  const lanTarget = machine.sshAddress || machine.hostname || machine.id;
-  const tailscaleTarget = machine.tailscaleName || machine.hostname || machine.id;
-  const route = isReachable(lanTarget) ? "lan" : "tailscale";
   return {
-    machineId,
-    target: route === "lan" ? lanTarget : tailscaleTarget,
-    route
+    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) {
@@ -11343,15 +11504,16 @@ 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;
   }
 }
 function runMachineCommand(machineId, command) {
   const resolved = resolveMachineCommand(machineId, command);
-  const result = spawnSync3("bash", ["-c", resolved.shellCommand], {
+  const result = spawnSync2("bash", ["-c", resolved.shellCommand], {
     encoding: "utf8",
     env: process.env
   });
@@ -11364,24 +11526,6 @@ function runMachineCommand(machineId, command) {
   };
 }
 
-// src/version.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname3, join as join2 } from "path";
-import { fileURLToPath } from "url";
-function getPackageVersion() {
-  try {
-    const here = dirname3(fileURLToPath(import.meta.url));
-    const candidates = [join2(here, "..", "package.json"), join2(here, "..", "..", "package.json")];
-    const pkgPath = candidates.find((candidate) => existsSync4(candidate));
-    if (!pkgPath) {
-      return "0.0.0";
-    }
-    return JSON.parse(readFileSync2(pkgPath, "utf8")).version || "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
 // src/compatibility.ts
 var DEFAULT_COMMANDS = [
   { command: "bun", required: true },
@@ -11390,7 +11534,7 @@ var DEFAULT_COMMANDS = [
 function defaultPackages() {
   return [{ name: "@hasna/machines", command: "machines", expectedVersion: getPackageVersion(), required: true }];
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function commandId(value) {
@@ -11441,7 +11585,7 @@ function defaultRunner2(machineId, command) {
   return runMachineCommand(machineId, command);
 }
 function inspectCommand(machineId, spec, runner) {
-  const command = shellQuote2(spec.command);
+  const command = shellQuote3(spec.command);
   const versionArgs = spec.versionArgs ?? "--version";
   const script = [
     `cmd=${command}`,
@@ -11470,7 +11614,7 @@ function fieldCommand(field) {
 }
 function inspectWorkspace(machineId, spec, runner) {
   const script = [
-    `path=${shellQuote2(spec.path)}`,
+    `path=${shellQuote3(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)"',
@@ -11608,6 +11752,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",
@@ -11715,7 +11870,7 @@ function getAppManager(machine, app) {
     return "winget";
   return "apt";
 }
-function shellQuote3(value) {
+function shellQuote4(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function buildAppCommand(machine, app) {
@@ -11736,7 +11891,7 @@ function buildAppCommand(machine, app) {
   return `sudo apt-get install -y ${packageName}`;
 }
 function buildAppProbeCommand(machine, app) {
-  const packageName = shellQuote3(getPackageName(app));
+  const packageName = shellQuote4(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`;
@@ -12272,7 +12427,7 @@ var notificationConfigSchema = exports_external.object({
 function sortChannels(channels) {
   return [...channels].sort((left, right) => left.id.localeCompare(right.id));
 }
-function shellQuote4(value) {
+function shellQuote5(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function hasCommand2(binary) {
@@ -12319,7 +12474,7 @@ ${message}
     };
   }
   if (hasCommand2("mail")) {
-    const command = `printf %s ${shellQuote4(message)} | mail -s ${shellQuote4(subject)} ${shellQuote4(channel.target)}`;
+    const command = `printf %s ${shellQuote5(message)} | mail -s ${shellQuote5(subject)} ${shellQuote5(channel.target)}`;
     const result = Bun.spawnSync(["bash", "-lc", command], {
       stdout: "pipe",
       stderr: "pipe",
@@ -12502,7 +12657,7 @@ async function testNotificationChannel(channelId, event = "manual.test", message
   };
 }
 // src/commands/ports.ts
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync3 } from "child_process";
 function parseSsOutput(output) {
   return output.trim().split(`
 `).map((line) => line.trim()).filter(Boolean).map((line) => {
@@ -12544,7 +12699,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 = spawnSync4("bash", ["-lc", command], { encoding: "utf8" });
+  const result = spawnSync3("bash", ["-lc", command], { encoding: "utf8" });
   if (result.status !== 0) {
     throw new Error(result.stderr || `Failed to list ports for ${targetMachineId}`);
   }
@@ -22072,6 +22227,7 @@ var MACHINE_MCP_TOOL_NAMES = [
   "machines_install_claude_diff",
   "machines_install_claude_preview",
   "machines_install_claude_apply",
+  "machines_route_resolve",
   "machines_ssh_resolve",
   "machines_ports",
   "machines_backup_preview",
@@ -22182,8 +22338,11 @@ function createMcpServer(version2) {
   }));
   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) }]
@@ -22248,6 +22407,7 @@ export {
   runAppsInstall,
   resolveTables,
   resolveSshTarget,
+  resolveMachineRoute,
   renderDomainMapping,
   renderDashboardHtml,
   removeNotificationChannel,
@@ -22331,5 +22491,7 @@ export {
   MACHINES_STORAGE_MODE_ENV,
   MACHINES_STORAGE_FALLBACK_ENV,
   MACHINES_STORAGE_ENV,
+  MACHINES_PACKAGE_NAME,
+  MACHINES_CONSUMER_CONTRACT_VERSION,
   CROSSREFS_KEY
 };