vssh 4.2.0__tar.gz → 4.2.1__tar.gz

{vssh-4.2.0 → vssh-4.2.1}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [v0.7.5] - 2026-05-22
+
+### Runtime
+
+- Add `vssh doctor` / `vssh setup-check` for AI-operator setup diagnostics:
+  effective binary, stale binary conflicts, secret source, Wire config, and peer
+  counts.
+- Add MCP `vssh_doctor` so Codex, Claude, Cursor, and other MCP clients can
+  diagnose VSSH before attempting execution or facts calls.
+- Prefer MCP-safe underscore tool names and deduplicate exposed tools.
+- Read native secrets from `/etc/vssh/secret` and `~/.vssh/secret` before
+  falling back to Wire-derived secrets.
+
+### Python SDK
+
+- Add `VSSH.doctor()` to call `vssh doctor --json`.
+
 ## [v0.7.4] - 2026-05-16
 
 ### Runtime

{vssh-4.2.0 → vssh-4.2.1}/HELP.md

@@ -27,6 +27,7 @@ vssh server
 export VSSH_SECRET=your-secret
 vssh shell hostname      # Interactive shell
 vssh run hostname "cmd"  # Execute command
+vssh doctor --json       # Diagnose setup before MCP/AI use
 ```
 
 ## CLI Commands
@@ -47,6 +48,7 @@ vssh get <host:path> <local>  # Download
 ```bash
 vssh status        # Show dashboard
 vssh list          # List all peers
+vssh doctor        # Diagnose binary, secret, config, and peers
 vssh version       # Show version
 ```
 

{vssh-4.2.0 → vssh-4.2.1}/Makefile

@@ -1,4 +1,4 @@
-VERSION := 0.7.4
+VERSION := 0.7.5
 BUILD_TIME := $(shell date -u '+%Y-%m-%d_%H:%M:%S')
 LDFLAGS := -ldflags "-s -w -X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME)"
 

{vssh-4.2.0 → vssh-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vssh
-Version: 4.2.0
+Version: 4.2.1
 Summary: Python SDK for the vssh AI-native remote execution daemon
 Project-URL: Homepage, https://github.com/meshpop/vssh
 Project-URL: Repository, https://github.com/meshpop/vssh
@@ -99,6 +99,7 @@ VSSH_SECRET=change-me vssh run web1 "df -h"
 # Show status
 vssh                 # Dashboard
 vssh list            # List all nodes
+vssh doctor --json   # Diagnose binary, secret, config, peers, and MCP readiness
 ```
 
 ## Commands
@@ -123,6 +124,7 @@ vssh get <src> <dst>    Download through native daemon
 vssh exec <node> <cmd>  Alias for native run
 vssh list               List all nodes
 vssh status             Show dashboard
+vssh doctor [--json]    Diagnose local setup
 vssh version            Show version
 vssh help               Show help
 ```
@@ -269,6 +271,7 @@ facts = client.facts("web1")
 fleet = client.facts_many(["web1", "db1"])
 results = client.exec_many(["web1", "db1"], "uptime")
 job = client.job_start("web1", "long-running-command")
+doctor = client.doctor()
 ```
 
 The Python SDK is a client layer for AI agents and automation. It calls the
@@ -278,13 +281,14 @@ Agent-facing MCP tools:
 
 | Tool | Purpose |
 |------|---------|
-| `vssh.hosts.list` | List known hosts for routing |
-| `vssh.exec.safe` | Execute read/diagnostic commands with policy blocking |
-| `vssh.exec` | Execute with policy checks and optional `allow_dangerous` |
-| `vssh.route.select` | Select the best host by capability, tag, and health |
-| `vssh.exec.routed` | Route first, then execute with policy/evidence |
-| `vssh.policy.check` | Classify a command before execution |
-| `vssh_exec`, `vssh_list`, `vssh_status` | Backward-compatible tool names |
+| `vssh_doctor` | Diagnose binary, secret source, wire config, peers, and MCP readiness |
+| `vssh_hosts_list` | List known hosts for routing |
+| `vssh_exec_safe` | Execute read/diagnostic commands with policy blocking |
+| `vssh_exec` | Execute with policy checks and optional `allow_dangerous` |
+| `vssh_route_select` | Select the best host by capability, tag, and health |
+| `vssh_exec_routed` | Route first, then execute with policy/evidence |
+| `vssh_policy_check` | Classify a command before execution |
+| `vssh_status`, `vssh_list` | Status and peer inventory |
 
 Commands matching destructive/service-impacting patterns such as `rm -rf`,
 `shutdown`, `reboot`, `docker rm`, `kubectl delete`, and `systemctl restart`
@@ -292,7 +296,7 @@ are blocked unless the caller sets `allow_dangerous: true` after explicit human
 approval. Every execution response is an evidence envelope with timestamps,
 policy decision, target, command, timeout, and the structured execution result.
 
-`vssh.hosts.list` returns agent-friendly records:
+`vssh_hosts_list` returns agent-friendly records:
 
 ```json
 {

{vssh-4.2.0 → vssh-4.2.1}/README.md

@@ -78,6 +78,7 @@ VSSH_SECRET=change-me vssh run web1 "df -h"
 # Show status
 vssh                 # Dashboard
 vssh list            # List all nodes
+vssh doctor --json   # Diagnose binary, secret, config, peers, and MCP readiness
 ```
 
 ## Commands
@@ -102,6 +103,7 @@ vssh get <src> <dst>    Download through native daemon
 vssh exec <node> <cmd>  Alias for native run
 vssh list               List all nodes
 vssh status             Show dashboard
+vssh doctor [--json]    Diagnose local setup
 vssh version            Show version
 vssh help               Show help
 ```
@@ -248,6 +250,7 @@ facts = client.facts("web1")
 fleet = client.facts_many(["web1", "db1"])
 results = client.exec_many(["web1", "db1"], "uptime")
 job = client.job_start("web1", "long-running-command")
+doctor = client.doctor()
 ```
 
 The Python SDK is a client layer for AI agents and automation. It calls the
@@ -257,13 +260,14 @@ Agent-facing MCP tools:
 
 | Tool | Purpose |
 |------|---------|
-| `vssh.hosts.list` | List known hosts for routing |
-| `vssh.exec.safe` | Execute read/diagnostic commands with policy blocking |
-| `vssh.exec` | Execute with policy checks and optional `allow_dangerous` |
-| `vssh.route.select` | Select the best host by capability, tag, and health |
-| `vssh.exec.routed` | Route first, then execute with policy/evidence |
-| `vssh.policy.check` | Classify a command before execution |
-| `vssh_exec`, `vssh_list`, `vssh_status` | Backward-compatible tool names |
+| `vssh_doctor` | Diagnose binary, secret source, wire config, peers, and MCP readiness |
+| `vssh_hosts_list` | List known hosts for routing |
+| `vssh_exec_safe` | Execute read/diagnostic commands with policy blocking |
+| `vssh_exec` | Execute with policy checks and optional `allow_dangerous` |
+| `vssh_route_select` | Select the best host by capability, tag, and health |
+| `vssh_exec_routed` | Route first, then execute with policy/evidence |
+| `vssh_policy_check` | Classify a command before execution |
+| `vssh_status`, `vssh_list` | Status and peer inventory |
 
 Commands matching destructive/service-impacting patterns such as `rm -rf`,
 `shutdown`, `reboot`, `docker rm`, `kubectl delete`, and `systemctl restart`
@@ -271,7 +275,7 @@ are blocked unless the caller sets `allow_dangerous: true` after explicit human
 approval. Every execution response is an evidence envelope with timestamps,
 policy decision, target, command, timeout, and the structured execution result.
 
-`vssh.hosts.list` returns agent-friendly records:
+`vssh_hosts_list` returns agent-friendly records:
 
 ```json
 {

vssh-4.2.1/cmd/vssh/doctor.go

@@ -0,0 +1,297 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/meshpop/vssh/internal/config"
+	"github.com/meshpop/vssh/internal/ssh"
+)
+
+type DoctorReport struct {
+	Kind        string        `json:"kind"`
+	Status      string        `json:"status"`
+	Checks      []DoctorCheck `json:"checks"`
+	NextActions []string      `json:"next_actions"`
+}
+
+type DoctorCheck struct {
+	Name   string `json:"name"`
+	Status string `json:"status"`
+	Detail string `json:"detail,omitempty"`
+	Next   string `json:"next,omitempty"`
+}
+
+func cmdDoctor(args []string) {
+	jsonOut := false
+	filtered := make([]string, 0, len(args))
+	for _, arg := range args {
+		if arg == "--json" {
+			jsonOut = true
+			continue
+		}
+		filtered = append(filtered, arg)
+	}
+	if len(filtered) != 0 {
+		fmt.Fprintln(os.Stderr, "Usage: vssh doctor [--json]")
+		os.Exit(1)
+	}
+	report := runDoctor()
+	if jsonOut {
+		writeJSON(report)
+		return
+	}
+	fmt.Print(formatDoctor(report))
+	if report.Status == "fail" {
+		os.Exit(1)
+	}
+}
+
+func runDoctor() DoctorReport {
+	report := DoctorReport{Kind: "vssh_doctor", Status: "ok"}
+	add := func(name, status, detail, next string) {
+		report.Checks = append(report.Checks, DoctorCheck{Name: name, Status: status, Detail: detail, Next: next})
+		if status == "fail" {
+			report.Status = "fail"
+		} else if status == "warn" && report.Status == "ok" {
+			report.Status = "warn"
+		}
+	}
+
+	if exe, err := os.Executable(); err == nil {
+		add("vssh_binary", "ok", exe, "")
+	} else {
+		add("vssh_binary", "fail", err.Error(), "reinstall vssh or run the expected binary explicitly")
+	}
+	add("vssh_version", "ok", fmt.Sprintf("vssh %s", version), "")
+	checkBinaryConflicts(add)
+	checkSecretSource(add)
+	checkWireConfig(add)
+	checkPeers(add)
+
+	switch report.Status {
+	case "ok":
+		report.NextActions = []string{
+			"Run vssh status.",
+			"Run vssh facts-many <hosts> before connecting AI operators.",
+			"Connect MCP clients to vssh mcp only when direct transport tools are needed.",
+		}
+	case "warn":
+		report.NextActions = []string{
+			"Review warning checks before relying on native execution.",
+			"Pin MCP clients to the intended vssh binary and shared secret.",
+		}
+	default:
+		report.NextActions = []string{
+			"Fix failed checks before starting vsshd or exposing vssh MCP.",
+		}
+	}
+	return report
+}
+
+func checkBinaryConflicts(add func(name, status, detail, next string)) {
+	current, _ := os.Executable()
+	candidates := vsshBinaryCandidates(current)
+	versions := map[string]string{}
+	for _, candidate := range candidates {
+		versions[candidate] = vsshBinaryVersion(candidate)
+	}
+	if len(versions) == 0 {
+		add("vssh_binary_conflict", "warn", "no executable vssh candidates found", "install vssh or add it to PATH")
+		return
+	}
+	if hasVersionConflict(versions) {
+		add("vssh_binary_conflict", "warn", formatVersions(versions), "remove stale vssh binaries or pin MCP clients to the intended binary")
+		return
+	}
+	add("vssh_binary_conflict", "ok", formatVersions(versions), "")
+}
+
+func checkSecretSource(add func(name, status, detail, next string)) {
+	source := secretSource()
+	if source == "" {
+		add("vssh_secret", "fail", "no VSSH_SECRET, secret file, or wire-derived secret", "set VSSH_SECRET or create ~/.vssh/secret on client and daemon")
+		return
+	}
+	secret := getSecret()
+	if strings.TrimSpace(secret) == "" {
+		add("vssh_secret", "fail", "secret source exists but no effective secret was produced", "verify secret file contents or wire config")
+		return
+	}
+	add("vssh_secret", "ok", source+"; value not displayed", "")
+}
+
+func checkWireConfig(add func(name, status, detail, next string)) {
+	cfg, err := config.LoadWireConfig()
+	if err != nil {
+		add("wire_config", "warn", "wire config not found", "standalone vssh can still work; configure peers or use explicit host:port")
+		return
+	}
+	detail := "node=" + cfg.NodeName
+	if cfg.ServerURL != "" {
+		detail += " server_url=set"
+	}
+	add("wire_config", "ok", detail, "")
+}
+
+func checkPeers(add func(name, status, detail, next string)) {
+	connector, err := ssh.NewConnector("default")
+	if err != nil {
+		add("peers", "warn", err.Error(), "verify wire/tailscale peer configuration or use explicit host:port targets")
+		return
+	}
+	peers := connector.ListPeers()
+	online := 0
+	now := time.Now().Unix()
+	for _, peer := range peers {
+		if peer.NodeName == "" {
+			continue
+		}
+		if peerOnline(peer, now) {
+			online++
+		}
+	}
+	if len(peers) == 0 {
+		add("peers", "warn", "peers=0", "configure peers before using routing, facts-many, or MCP host selection")
+		return
+	}
+	add("peers", "ok", fmt.Sprintf("peers=%d online=%d", len(peers), online), "")
+}
+
+func peerOnline(peer config.Peer, now int64) bool {
+	if peer.Online != nil {
+		return *peer.Online
+	}
+	if peer.LastSeen == nil {
+		return false
+	}
+	switch v := peer.LastSeen.(type) {
+	case float64:
+		return now-int64(v) < 60
+	case int64:
+		return now-v < 60
+	case string:
+		if t, err := time.Parse(time.RFC3339, v); err == nil {
+			return time.Since(t) < 60*time.Second
+		}
+	}
+	return false
+}
+
+func secretSource() string {
+	if strings.TrimSpace(os.Getenv("VSSH_SECRET")) != "" {
+		return "env:VSSH_SECRET"
+	}
+	for _, path := range []string{"/etc/vssh/secret", filepath.Join(homeDir(), ".vssh", "secret")} {
+		if st, err := os.Stat(path); err == nil && !st.IsDir() {
+			return path
+		}
+	}
+	if strings.TrimSpace(os.Getenv("WIRE_SERVER_URL")) != "" {
+		return "env:WIRE_SERVER_URL derived"
+	}
+	if _, err := config.LoadWireConfig(); err == nil {
+		return "wire config derived"
+	}
+	return ""
+}
+
+func homeDir() string {
+	home, _ := os.UserHomeDir()
+	return home
+}
+
+func vsshBinaryCandidates(current string) []string {
+	seen := map[string]bool{}
+	add := func(path string) {
+		if path == "" || seen[path] {
+			return
+		}
+		if st, err := os.Stat(path); err == nil && !st.IsDir() && st.Mode()&0111 != 0 {
+			seen[path] = true
+		}
+	}
+	add(current)
+	if path, err := exec.LookPath("vssh"); err == nil {
+		add(path)
+	}
+	add(filepath.Join(homeDir(), "bin", "vssh"))
+	add("/usr/local/bin/vssh")
+	add("/opt/homebrew/bin/vssh")
+	for _, dir := range filepath.SplitList(os.Getenv("PATH")) {
+		add(filepath.Join(dir, "vssh"))
+	}
+	out := make([]string, 0, len(seen))
+	for path := range seen {
+		out = append(out, path)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func vsshBinaryVersion(path string) string {
+	out, err := exec.Command(path, "--version").CombinedOutput()
+	if err != nil {
+		return "unknown"
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func hasVersionConflict(versions map[string]string) bool {
+	seen := map[string]bool{}
+	for _, version := range versions {
+		if version == "" || version == "unknown" {
+			continue
+		}
+		seen[version] = true
+	}
+	return len(seen) > 1
+}
+
+func formatVersions(versions map[string]string) string {
+	paths := make([]string, 0, len(versions))
+	for path := range versions {
+		paths = append(paths, path)
+	}
+	sort.Strings(paths)
+	parts := make([]string, 0, len(paths))
+	for _, path := range paths {
+		parts = append(parts, path+"="+versions[path])
+	}
+	return strings.Join(parts, "; ")
+}
+
+func formatDoctor(report DoctorReport) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "vssh doctor status=%s\n", report.Status)
+	for _, check := range report.Checks {
+		fmt.Fprintf(&b, "- %s: %s", check.Name, check.Status)
+		if check.Detail != "" {
+			fmt.Fprintf(&b, " | %s", check.Detail)
+		}
+		if check.Next != "" {
+			fmt.Fprintf(&b, " | next: %s", check.Next)
+		}
+		b.WriteByte('\n')
+	}
+	if len(report.NextActions) > 0 {
+		b.WriteString("next_actions:\n")
+		for _, action := range report.NextActions {
+			fmt.Fprintf(&b, "- %s\n", action)
+		}
+	}
+	return b.String()
+}
+
+func doctorJSON(report DoctorReport) map[string]interface{} {
+	payload, _ := json.Marshal(report)
+	out := map[string]interface{}{}
+	json.Unmarshal(payload, &out)
+	return out
+}

{vssh-4.2.0 → vssh-4.2.1}/cmd/vssh/main.go

@@ -19,7 +19,7 @@ import (
 )
 
 var (
-	version   = "0.7.4"
+	version   = "0.7.5"
 	buildTime = ""
 )
 
@@ -65,6 +65,8 @@ func main() {
 		cmdArtifactCollect(os.Args[2:])
 	case "setup":
 		cmdSetup()
+	case "doctor", "setup-check", "install-check":
+		cmdDoctor(os.Args[2:])
 	case "status":
 		cmdStatus()
 	case "list", "ls":
@@ -115,6 +117,7 @@ Usage:
   vssh bench <host> [count]   Measure native exec latency
 
   vssh status                 Show connection status
+  vssh doctor [--json]        Diagnose local binary, secret, peers, and MCP readiness
   vssh list                   List all peers
   vssh agent                  Run monitoring agent
   vssh mcp                    Run MCP JSON-RPC server